Simple library for changing language on client site with Astro
MIT License
npm install astro-static-dict
yarn add astro-static-dict
pnpm add astro-static-dict
bun install astro-static-dict
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.
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.
interface DictionaryBranch<T = string> extends Record<string, DictionaryBranch<T> | T> {}
---
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,
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 |
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
}
})
]
})
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 |
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.
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 |
interface Window {
changeLanguage(newLanguage: string): void
}
// or
window.dispatchEvent(new CustomEvent('changeLanguage', { detail: newLanguage }))
interface Window {
changeLanguage(newLanguage: string): void,
selectedLanguage: string,
cachedDictionaries: Partial<Record<string, DictionaryBranch>>
}