helpwave internationlization

helpwaves package for internationalization that creates localized and typesafe translation based on ARB files.

Usage

Create a .arb file with your translations:

{
"priceInfo": "The price is {price}{currency, select, usd{$USD} eur{€} other{}}.",
"@priceInfo": {
"placeholders": {
"price": {
"type": "number"
},
"currency": {}
}
}
}

And get a translation:

import{combineTranslation}from"@helpwave/internationalization";import{Translation}from"@helpwave/internationalization";translations["en-US"].priceInfo?.({price, currency})typeExtensionType={name: string}constextension: Translation<"fr-FR",ExtensionType>={"fr-FR": {name: "Charlemagne"}}constt=combineTranslation([translations,extension],"en-US")// typesafe on both function parameters // and handles errors automatically -> return = {{${locale}:${String(key)}}}t("priceInfo",{ price, currency })

Getting Started

Install the package

npm install -D @helpwave/internationalization

Create local ARB files

The file structure could look like this:

/locales
-> de-DE.arb
-> en-US.arb
/locales/time
-> de-DE.arb
-> en-US.arb

Then run:

npx build-intl 

By default ./locales will be translated to ./i18n, the input directory and output file are configurable with:

Usage: i18n-compile [options]
Options:
-i, --in <dir> Input directory containing .arb files
-o, --out <file> Output file (e.g. ./i18n/translations.ts)
-f, --force Overwrite output without prompt
-h, --help Show this help message
`)

Tests

The lexer, parser and compiler are all tested with jest, see our tests

Examples

Example translation files and the resulting translation can be found in the examples folder.

Rebuild the examples:

npm run build
node dist/scripts/compile-arb.js --force -i ./examples/locales -o ./examples/translations/translations.ts -n "exampleTranslation"

React hook example:

typeUseHidetideTranslationOverwrites={locale?: HightideTranslationLocales,}typeHidetideTranslationExtension<Lextendsstring,TextendsTranslationEntries>=PartialTranslationExtension<L,HightideTranslationLocales,T,HightideTranslationEntries>exportfunctionuseHightideTranslation<Lextendsstring,TextendsTranslationEntries>(extensions?: SingleOrArray<HidetideTranslationExtension<L,T>>,overwrites?: UseHidetideTranslationOverwrites){const{locale: inferredLocale}=useLocale()constlocale=overwrites?.locale??inferredLocaleconsttranslationExtensions=ArrayUtil.resolveSingleOrArray(extensions)returncombineTranslation<L|HightideTranslationLocales,T&HightideTranslationEntries>([
...translationExtensions,hightideTranslationasHidetideTranslationExtension<L,T>],locale)}