Search…
Translator
Customisable translator for backend and frontend usage with a statically typed translations facade.
Source code is hosted on GitHub
  • 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:

Static translation access

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.

Custom interpolations

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"

Custom formatting

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

Custom placeholders

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"

createTranslator()

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

createTranslatorAccessor()

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:

Translator.config()

Configure translator:
import { createTranslator } from "@corets/translator"
const translator = createTranslator({ ... }, { language: "en" })
translator.config({
language: "en",
fallbackLanguage: "de",
interpolate: true,
formatter,
interpolator,
placeholder,
})

Translator.getLanguage()

Get current language:
translator.getLanguage()

Translator.setLanguage()

Change current language:
translator.setLanguage("en")

Translator.getLanguages()

Get all registered languages:
translator.getLanguages()

Translator.getFallbackLanguage()

Get fallback language:
transaltor.getFallbackLanguage()
A fallback language is used whenever a translation key is missing for current language.

Translator.setFallbackLanguage()

Change fallback language:
translator.setFallbackLanguage("de")

Translator.getTranslations()

Get all registered translations:
translator.getTranslations()
Returned object looks something like this:
{
en: { key: "value" },
de: { key: "value" },
}

Translator.getTranslationsForLanguage()

Get all translations for a specific language:
translator.getTranslationsForLanguage("en")
The returned object looks something like this:
{ key: "value" }

Translator.setTranslations()

Replace all translations, for all languages, with the new ones:
translator.setTranslations({ en: { key: "value" }})

Translator.setTranslationsForLanguage()

Replace all translations for a specific language:
translator.setTranslationsForLanguage("en", { key: "value" })

Translator.addTranslations()

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.

Translator.addTranslationsForLanguage()

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.

Translator.get()

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 out documentation for formatter, interpolator, and placeholder.

Translator.has()

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

Translator.t()

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")
This method supports the same options object as Translator.get().

Translator.listen()

Listen to any kind of changes, like language change, translations change, etc.:
const unsubscribe = translator.listen(() => console.log("something has changed"))
unsubscribe()
Copy link
On this page
Static translation access
Custom interpolations
Custom formatting
Custom placeholders
createTranslator()
createTranslatorAccessor()
Translator.config()
Translator.getLanguage()
Translator.setLanguage()
Translator.getLanguages()
Translator.getFallbackLanguage()
Translator.setFallbackLanguage()
Translator.getTranslations()
Translator.getTranslationsForLanguage()
Translator.setTranslations()
Translator.setTranslationsForLanguage()
Translator.addTranslations()
Translator.addTranslationsForLanguage()
Translator.get()
Translator.has()
Translator.t()
Translator.listen()