astro-static-dict

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

Property	Type	Description
dictionary	DictionaryBranch	Default dictionary used for development, it is also used for typing your created dictionary.
isDev	boolean	Always pass import.meta.env.DEV into it
keySeparator	string	Default: @@@ Used to separate dictionary keys in build process
keySuffix	string	Default: !!! Used to end data-dict attribute in build process

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

Property	Type	Description
dictionary	DictionaryBranch	Default language dictionary for build process
dictionaries	Record<string, DictionaryBranch>	All your dictionaries that will be transformed into JSON files
keySeparator	string	Default: !!! Must be the same as initDictionary's keySeparator
keySuffix	string	Default: !!! Must be the same as initDictionary's keySuffix

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

Property	Type	Description
cachedDictionaries	Record<string, DictionaryBranch>	Dictionaries that will be injected into window.cachedDictionaries, you must include dictionary used in build process but more is up to you
defaultLanguage	string	Name of default language used on a page. Must be the same as dictionary used in build process
keySeparator	string	Default: @@@ Must be the same as initDictionary's keySeparator
keySuffix	string	Default: !!! Must be the same as initDictionary's keySuffix

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>>
}