text: (window.webpackJsonp=window.webpackJsonp||[]).push([[23],{CHnl:function(e,a,t){"use strict";t.r(a),t.d(a,"_frontmatter",(function(){return o})),t.d(a,"default",(function(){return i}));var n=t("Fcif"),r=t("+I+c"),l=(t("mXGw"),t("/FXl")),s=t("BIGe"),o=(t("aD51"),{});void 0!==o&&o&&o===Object(o)&&Object.isExtensible(o)&&!o.hasOwnProperty("__filemeta")&&Object.defineProperty(o,"__filemeta",{configurable:!0,value:{name:"_frontmatter",filename:"src/pages/translator.mdx"}});var c={_frontmatter:o},b=s.a;function i(e){var a=e.components,t=Object(r.a)(e,["components"]);return Object(l.b)(b,Object(n.a)({},c,t,{components:a,mdxType:"MDXLayout"}),Object(l.b)("h1",{id:"translator"},"Translator"),Object(l.b)("p",null,"Simple translation library that works everywhere."),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-bash"}),"yarn add @corets/translator\n")),Object(l.b)("h2",{id:"react"},"React"),Object(l.b)("p",null,"Before you can start using this library inside React, you have to add the ",Object(l.b)("a",Object(n.a)({parentName:"p"},{href:"/use-translator"}),"@corets/use-translator")," package first. It provides a seamless integration through a hooks based API."),Object(l.b)("h2",{id:"custom-interpolations"},"Custom interpolations"),Object(l.b)("p",null,"Provide a custom interpolation function, that is replacing placeholders with replacements:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'import { createTranslator } from "@corets/translator"\n\nconst customInterpolator = (text: string, match: string, replacement: any) => {\n  return text.replace(`{ ${match} }`, replacement)\n}\n\nconst translator = createTranslator({}, { interpolator: customInterpolator })\n')),Object(l.b)("h2",{id:"custom-formatting"},"Custom formatting"),Object(l.b)("p",null,"Provide a custom formatter function, that formats replacements:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'import { createTranslator, formatter } from "@corets/translator"\nimport dayjs from "dayjs"\n\nconst customFormatter = (language: string, replacement: any, replacements: object) => {\n  // custom formatting for dates\n  if (replacement instanceof Date) {\n    const format = replacements?.format ?? "DD.MM.YYYY"\n\n    return dayjs(replacement).format(format)\n  }\n\n  // fallback to default behaviour\n  return formatter(language, replacement, replacements)\n}\n\nconst translator = createTranslator({}, { formatter: customFormatter })\n')),Object(l.b)("h2",{id:"custom-placeholder-for-missing-keys"},"Custom placeholder for missing keys"),Object(l.b)("p",null,"Provide a custom placeholder for missing translation keys:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'import { createTranslator } from "@corets/translator"\n\nconst customPlaceholder = (language: string, key: string, replacements: object) => `${language}.${key}`\n\nconst translator = createTranslator({}, { placeholder: customPlaceholder })\n')),Object(l.b)("h2",{id:"createtranslator"},Object(l.b)("inlineCode",{parentName:"h2"},"createTranslator")),Object(l.b)("p",null,"Creates a new instance of ",Object(l.b)("inlineCode",{parentName:"p"},"Translator"),"."),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'import { createTranslator } from "@corets/translator"\n\nconst translations = {\n  en: { title: "Welcome" },\n  de: { title: "Willkommen" }\n}\n\nconst translator = createTranslator(translations, { language: "en" })\n')),Object(l.b)("p",null,"Create a translator instance without the factory function:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'import { Translator } from "@corets/translator"\n\nconst translator = new Translator({}, { language: "en" })\n')),Object(l.b)("h2",{id:"translatorconfig"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.config")),Object(l.b)("p",null,"Configure translator:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'import { createTranslator } from "@corets/translator"\n\nconst translator = createTranslator({}, { language: "en" })\n\ntranslator.config({\n  // current language\n  language: "en",\n  // fallback to another language if the translation key is missing\n  fallbackLanguage: "de",\n  // should translations be templatized? (default: true)\n  templatize: true,\n  // custom replacements formatter\n  formatter,\n  // custom message interpolator\n  interpolator,\n  // custom formatter for missing translation keys\n  placeholder,\n})\n')),Object(l.b)("h2",{id:"translatorgetlanguage"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.getLanguage")),Object(l.b)("p",null,"Get current language:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),"translator.getLanguage()\n")),Object(l.b)("h2",{id:"translatorsetlanguage"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.setLanguage")),Object(l.b)("p",null,"Change current language:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.setLanguage("en")\n')),Object(l.b)("h2",{id:"translatorgetlanguages"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.getLanguages")),Object(l.b)("p",null,"Get all registered languages:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),"translator.getLanguages()\n")),Object(l.b)("h2",{id:"translatorgetfallbacklanguage"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.getFallbackLanguage")),Object(l.b)("p",null,"Get fallback language:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),"transaltor.getFallbackLanguage()\n")),Object(l.b)("p",null,Object(l.b)("strong",{parentName:"p"},"Note:")," A fallback language is used whenever a translation key is missing from the current language."),Object(l.b)("h2",{id:"translatorsetfallbacklanguage"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.setFallbackLanguage")),Object(l.b)("p",null,"Change fallback language:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.setFallbackLanguage("de")\n')),Object(l.b)("h2",{id:"translatorgettranslations"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.getTranslations")),Object(l.b)("p",null,"Get all registered translations:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),"translator.getTranslations()\n")),Object(l.b)("p",null,"The returned object looks something like this:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'{\n  en: { key: "value" },\n  de: { key: "value" },\n}\n')),Object(l.b)("h2",{id:"translatorgettranslationsforlanguage"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.getTranslationsForLanguage")),Object(l.b)("p",null,"Get all translations for a specific langauge:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.getTranslationsForLanguage("en")\n')),Object(l.b)("p",null,"The returned object looks something like this:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'{\n  key: "value"\n}\n')),Object(l.b)("h2",{id:"translatorsettranslations"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.setTranslations")),Object(l.b)("p",null,"Replace all translations, for all languages, with new ones:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.setTranslations({ en: { key: "value" }})\n')),Object(l.b)("h2",{id:"translatorsettranslationsforlanguage"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.setTranslationsForLanguage")),Object(l.b)("p",null,"Replace all translations for a specific language:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.setTranslationsForLanguage("en", { key: "value" })\n')),Object(l.b)("h2",{id:"translatoraddtranslations"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.addTranslations")),Object(l.b)("p",null,"Add translations, for all languages, using a merge:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.addTranslations({ de: { key: "value" } })\n')),Object(l.b)("p",null,Object(l.b)("strong",{parentName:"p"},"Note:")," Contrary to the ",Object(l.b)("a",Object(n.a)({parentName:"p"},{href:"#translatorsettranslations"}),Object(l.b)("inlineCode",{parentName:"a"},"Translator.setTranslations()"))," method, this one will not replace all translations but do a merge instead."),Object(l.b)("h2",{id:"translatoraddtranslationsforlanguage"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.addTranslationsForLanguage")),Object(l.b)("p",null,"Add translations, for a specific language, using a merge:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.addTranslationsForLanguage("en", { key: "value" })\n')),Object(l.b)("p",null,Object(l.b)("strong",{parentName:"p"},"Note:")," Contrary to the ",Object(l.b)("a",Object(n.a)({parentName:"p"},{href:"#translatorsettranslationsforlanguage"}),Object(l.b)("inlineCode",{parentName:"a"},"Translator.setTranslationsForLanguage()"))," method, this one will not replace all translations but do a merge instead."),Object(l.b)("h2",{id:"translatorget"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.get")),Object(l.b)("p",null,"Retrieve a translation:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.get("key")\n')),Object(l.b)("p",null,"Retrieve a translation with a nested key:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.get("nested.key")\n')),Object(l.b)("p",null,"Retrieve translation for another language:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.get("key", { language: "de" })\n')),Object(l.b)("p",null,"Retrieve translation with another fallback language:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.get("key", { fallbackLanguage: "de" })\n')),Object(l.b)("p",null,"Retrieve translation without templatizing it:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.get("key", { templatize: false })\n')),Object(l.b)("p",null,"Retrieve a translation and interpolate some values, using array syntax:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'// given translation at "key" is "Did you know, $1 and $2 are colors?"\ntranslator.get("key", ["red", "blue"])\n// you\'ll get "Did you know, red and blue are colors?"\n')),Object(l.b)("p",null,"Retrieve a translation and interpolate some values, using object syntax:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'// given translation at "key" is "Did you know, $color1 and $color2 are colors?"\ntranslator.get("key", { color1: "red", color2: "blue" })\n// you\'ll get "Did you know, red and blue are colors?"\n')),Object(l.b)("p",null,"Retrieve translation with a custom formatter, interpolator and placeholder:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.get("key", { formatter, interpolator, placeholder })\n')),Object(l.b)("p",null,Object(l.b)("strong",{parentName:"p"},"Note:")," Read more about ",Object(l.b)("a",Object(n.a)({parentName:"p"},{href:"#custom-formatting"}),"formatter"),", ",Object(l.b)("a",Object(n.a)({parentName:"p"},{href:"#custom-interpolations"}),"interpolator"),", and ",Object(l.b)("a",Object(n.a)({parentName:"p"},{href:"#custom-placeholder-for-missing-keys"}),"placeholder"),"."),Object(l.b)("h2",{id:"translatorhas"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.has")),Object(l.b)("p",null,"Check if translation exists:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.has("key")\n')),Object(l.b)("p",null,"Check if translation exists for a specific language:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.has("key", { language: "en" })\n')),Object(l.b)("p",null,"Check if translation exists in the current langauge or in a specific fallback language:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'translator.has("key", { fallbackLanguage: "de" })\n')),Object(l.b)("h2",{id:"translatort"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.t")),Object(l.b)("p",null,"Create a dedicated translation function:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'const t = translator.t()\n\nt("key")\n')),Object(l.b)("p",null,"Create a translation function for a specific scope:"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'const t = translator.t("nested.key")\n\n// the actual path will be "nested.key.key"\nt("key")\n')),Object(l.b)("p",null,"Override scope with ",Object(l.b)("inlineCode",{parentName:"p"},"~"),":"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'const t = translator.t("nested.key")\n\n// the actual path will be "key"\nt("~key")\n')),Object(l.b)("p",null,Object(l.b)("strong",{parentName:"p"},"Note:")," Method ",Object(l.b)("inlineCode",{parentName:"p"},"Translator.t")," as well as the translate function accept the same options as the ",Object(l.b)("a",Object(n.a)({parentName:"p"},{href:"#translatorget"}),Object(l.b)("inlineCode",{parentName:"a"},"Translator.get()"))," method."),Object(l.b)("h2",{id:"translatorlisten"},Object(l.b)("inlineCode",{parentName:"h2"},"Translator.listen")),Object(l.b)("p",null,"Listen to any kind of changes (like language change, translations change, etc.):"),Object(l.b)("pre",null,Object(l.b)("code",Object(n.a)({parentName:"pre"},{className:"language-ts"}),'const unsubscribe = translator.listen((translator) => console.log("something changed"))\n\n// unsubscribe from changes\nunsubscribe()\n')))}void 0!==i&&i&&i===Object(i)&&Object.isExtensible(i)&&!i.hasOwnProperty("__filemeta")&&Object.defineProperty(i,"__filemeta",{configurable:!0,value:{name:"MDXContent",filename:"src/pages/translator.mdx"}}),i.isMDXComponent=!0}}]);
  //# sourceMappingURL=component---src-pages-translator-mdx-8d2088e939b029924d73.js.map