Astro static dict

Astro static dict is a library for lightweight client side language change for Astro

Installation

npm install astro-static-dict
yarn add astro-static-dict

Live demo

Motivation

We dont really want to use another frameworks (react, svelte, solid...) just to change language on client side, and according to Astro documentation we should be building separated HTML for each language. This is fine, but it can feel pretty slow and page refresh is not the best for user experience.

How it works

When building your site astro-static-dict integration parses all built HTML files by adding data-dict attribute based on language key you passed, it also converts all your dictionary objects to JSON. Later - on client browser, when language is changed it downloads new JSON dictionary, and replaces every node with data-dict attribute with new text.

DictionaryBranch interface

interface DictionaryBranch<T = string> extends Record<string, DictionaryBranch<T> | T> {}

Server side

---
import { initDictionary } from 'astro-static-dict/server'
import { enUs } from 'lib/locale'
import Layout from 'lib/layouts/Layout.astro'

const T = initDictionary({
    dictionary: enUs,
    isDev: import.meta.env.DEV
})
---

<Layout>
    <h1>
        {T.hello}
    </h1>
</Layout>

You can initialize new dictionary with initDictionary method imported from astro-static-dict/server. You can initalize new one per component or have some place where you initalize it and export into other components, pages etc,

initDictionary config

Integration

import { defineConfig } from 'astro/config'
import { astroStaticDict } from 'astro-static-dict/integration'
import { enUs, plPl } from 'lib/locale'

export default defineConfig({
    integrations: [
        astroStaticDict({
            dictionary: enUs,
            dictionaries: {
                enUs,
                plPl
            }
        })
    ]
})

astroStaticDict integration config

Client

import { watchLanguageChange } from 'astro-static-dict/client'
import { enUs } from 'lib/locale'

watchLanguageChange({
    cachedDictionaries: {
        enUs
    },
    defaultLanguage: 'enUs'
})

It listens for changeLanguage event - when this event is trigerred it downloads dictionary in JSON format and replaces every text node on website.

watchLanguageChange config

Trigger language change

interface Window {
    changeLanguage(newLanguage: string): void
}
// or
window.dispatchEvent(new CustomEvent('changeLanguage', { detail: newLanguage }))

Window modified properties

interface Window {
    changeLanguage(newLanguage: string): void,
    selectedLanguage: string,
    cachedDictionaries: Partial<Record<string, DictionaryBranch>>
}