Translator
Customisable translator for backend and frontend usage with a statically typed translations facade.
- Works for server side and client side translations handling
- Features static translations access, without using string based keys
- Extremely easy to use and customise
- Not bloated with unnecessary features
yarn
npm
yarn add @corets/translator
npm install --save @corets/translator
Seamless React integration is shipped in a separate package:
Translations can be accessed in a static manner thanks to the
createTranslatorAccessor() helper. Check out @corets/use-translator docs for an example usage in React.Provide a custom interpolation function used for replacement of placeholders with values:
import { createTranslator } from "@corets/translator"
const customInterpolator = (text: string, match: string, replacement: any) => {
return text.replace(`[[${match}]]`, replacement)
}
const translator = createTranslator({}, { interpolator: customInterpolator })
You can access the default interpolation function anytime:
import { translatorInterpolator } from "@corets/translator"
Provide a custom formatter function used to format replacements before interpolation:
import { createTranslator, translatorFormatter } from "@corets/translator"
import dayjs from "dayjs"
const customFormatter = (language: string, replacement: any, replacements: object) => {
if (replacement instanceof Date) {
const format = replacements?.format ?? "DD.MM.YYYY"
return dayjs(replacement).format(format)
}
return defaultTranslatorFormatter(language, replacement, replacements)
}
const translator = createTranslator({}, { formatter: customFormatter })
Provide a custom placeholder function used to generate placeholders for missing translation keys:
import { createTranslator } from "@corets/translator"
const customPlaceholder = (language: string, key: string, replacements: object) => `${language}.${key}`
const translator = createTranslator({}, { placeholder: customPlaceholder })
You can access the default placeholder function anytime:
import { translatorPlaceholder } from "@corets/translator"
Create a new
Translator instance:import { createTranslator } from "@corets/translator"
const translations = {
en: { title: "Welcome" },
de: { title: "Willkommen" }
}
const translator = createTranslator(translations, { language: "en" })
Create a translator instance without the factory function:
import { Translator } from "@corets/translator"
const translator = new Translator({}, { language: "en" })
Create a statically typed facade for your translations. This allows you to access translations in a statically typed manner, no need to use string based translation keys anymore. Trying to access missing translations will lead to a compilation error! 💥
import { createTranslator, createTranslatorAccessor } from "@corets/translator"
const translations = {
en: { some: { nested: "value", another: "Hello {greeting}"} },
de: { some: { nested: "other"} },
}
const translator = createTranslator(translations, { language: "en" })
const locales = createTranslatorAccessor(translator, translations.en)
locales.some.nested.get()
locales.some.another.get({ replace: { greeting: "World" } })
locales.some.nested.get({ language: "de" })
This functionality is powered by the accessor library:
Configure translator:
import { createTranslator } from "@corets/translator"
const translator = createTranslator({ ... }, { language: "en" })
translator.config({
language: "en",
fallbackLanguage: "de",
interpolate: true,
formatter,
interpolator,
placeholder,
})
Get current language:
translator.getLanguage()
Change current language:
translator.setLanguage("en")
Get all registered languages:
translator.getLanguages()
Get fallback language:
transaltor.getFallbackLanguage()
A fallback language is used whenever a translation key is missing for current language.
Change fallback language:
translator.setFallbackLanguage("de")
Get all registered translations:
translator.getTranslations()
Returned object looks something like this:
{
en: { key: "value" },
de: { key: "value" },
}
Get all translations for a specific language:
translator.getTranslationsForLanguage("en")
The returned object looks something like this:
{ key: "value" }
Replace all translations, for all languages, with the new ones:
translator.setTranslations({ en: { key: "value" }})
Replace all translations for a specific language:
translator.setTranslationsForLanguage("en", { key: "value" })
Update all translations, in all languages, using a merge:
translator.addTranslations({ de: { key: "value" } })
Contrary to the Translator.setTranslations() method, this one will not replace all translations but do a merge instead.
Add translations, for a specific language, using a merge:
translator.addTranslationsForLanguage("en", { key: "value" })
Contrary to the Translator.setTranslationsForLanguage() method, this one will not replace all translations but do a merge instead.
Retrieve a translation:
translator.get("key")
Retrieve a translation with a nested key:
translator.get("nested.key")
Retrieve translation for another language:
translator.get("key", { language: "de" })
Retrieve translation with another fallback language:
translator.get("key", { fallbackLanguage: "de" })
Retrieve translation without interpolating it:
translator.get("key", { interpolate: false })
Retrieve a translation and interpolate some values, using array syntax:
// given translation: {{1}} and {{2}} are colors
translator.get("key", ["red", "blue"])
Retrieve a translation and interpolate some values, using object syntax:
// given translations: {{color1}} and {{color2}} are colors
translator.get("key", { color1: "red", color2: "blue" })
Retrieve translation with a custom formatter, interpolator and placeholder:
translator.get("key", { formatter, interpolator, placeholder })
Check if translation exists:
translator.has("key")
Check if translation exists for a specific language:
translator.has("key", { language: "en" })
Check if translation exists in the current language or in a specific fallback language:
translator.has("key", { fallbackLanguage: "de" })
Create a standalone translation function:
const t = translator.t()
t("key")
// same as
translator.get("key")
Create a translation function for a specific scope:
const t = translator.t("nested.scope")
t("key")
// same as
translator.get("nested.scope.key")
Override scope with
~:const t = translator.t("nested.key")
t("~key")
// same as
translator.get("key")
Listen to any kind of changes, like language change, translations change, etc.:
const unsubscribe = translator.listen(() => console.log("something has changed"))
unsubscribe()
Last modified 1yr ago