![\"NPM](\"https://img.shields.io/npm/v/i18n-babel.svg\")
\n![\"NPM](\"https://img.shields.io/npm/dm/i18n-babel.svg\")
\n\n# i18n-babel\n\ni18n-babel is the most powerful translations manager for javascript applications on the web.\n\n- Easy to integrate: min to no effort\n- Automatically detects new strings\n- No external dependencies: only javascript and html :)\n- Blazing fast: it is a web component\n- Works with any framework (React, Angular, Stencil, ... even with plain Javascript)\n- Automatic language detection from naviagator user preferences\n- The key is the fallback: if no translation is found, the application will show the texts as defined\n- Local translations with intelligent update system\n- Versioning of translations with local cache in localstorage\n- Supports interpolation\n- Privacy friendly: local values can be opted-in/out\n- Small footprint: ~15 kB (4.5 kB gzipped)\n- Free to use\n\n# Gold sponsors\n\nFrom the creators of ***i18n-babel***: translations as a service - [blablatec.com](https://blablatec.com)\n\nMove your application to the next level: the premium translations service. With [blablatec.com](https://blablatec.com) you can focus on what you do best: add value to your application, surrounding with valuable partners.\n\n[Blablatec.com](https://blablatec.com) helps you to manage the translations with an easy and intuitive interface and keep the texts of your application always up to date.\n\n# Local values and Cookie Policies\n\nThis library uses cookie `lang` which must be opted in by setting `isLocalValuesAllowed: true` on initialization.\nIt also uses localstorage to keep the last version of the translation of each language in local storage. It must be opted in in the same way as cookie.\n\n# Index\n\n- [i18n-babel](#i18n-babel)\n- [Gold sponsors](#Gold-sponsors)\n- [Local values and Cookie Policies](#Local-values-and-Cookie-Policies)\n- [Index](#Index)\n- [How it works](#How-it-works)\n - [Configuration](#Configuration)\n - [Initialization](#Initialization)\n - [Modes](#Modes)\n * [Tag name](#Tag-name)\n * [Code](#Code)\n * [Attribute](#Attribute)\n- [Quick examples](#Quick-examples)\n - [Example of use with plain Javascript](#Example-of-use-with-plain-Javascript)\n - [Example of use with stencil.js app](#Example-of-use-with-stenciljs-app)\n * [Install](#Install)\n * [Usage](#Usage)\n- [API](#API)\n - [Events](#Events)\n * [Example:]#(Example)\n - [Translator](#Translator)\n * [`init(options?: ITranslatorOptions) => Translator`]#(initoptions-ITranslatorOptions--Translator)\n * [`getInstance() => Translator`]#(getInstance--Translator)\n * [`setLocalValuesAllowed(isLocalValuesAllowed = false) => void`]#(setLocalValuesAllowedisLocalValuesAllowed--false--void)\n * [`t(originalText: string, tData?: TypeTData, lang?: string) => PromiseTranslate me!
\n\n```\n\nIt also supports dynamic interpolation via `data-i18n` attribute:\n\n```html\nHello ${name}
\n\n```\n\n# Quick examples\n\nSee examples in [examples folder](https://github.com/i18n-babel/i18n-babel/tree/master/examples):\n- [Plain Javascript](https://github.com/i18n-babel/i18n-babel/tree/master/examples/plain-js)\n- [Stencil](https://github.com/i18n-babel/i18n-babel/tree/master/examples/stencil)\n- [React](https://github.com/i18n-babel/i18n-babel/tree/master/examples/react)\n- [Vue](https://github.com/i18n-babel/i18n-babel/tree/master/examples/vue)\n- [Angular](https://github.com/i18n-babel/i18n-babel/tree/master/examples/angular)\n\n## Example of use with plain Javascript\n\n`index.html`\n```html\n\n\n\n\n \n\n\n\ndata-i18n\n
\n
` style translations\n missingTag: 'app', // all new detected strings will be tagged as app when sent to server\n tags: ['app'], // download only app tagged strings\n});\n```\n\nIf any function from `Translator` is used before calling `init`, `Translator` will automatically be initialized with following values. Those are also the default values when called `init` with no options:\n\n```js\nconst translator = Translator.init({\n availableLangs: ['en'],\n defaultLanguage: 'en',\n userLanguage: null,\n isShowMissing: false,\n isLocalValuesAllowed: false,\n isEnableAttr: false,\n tags: [],\n missingTag: 'app',\n assetsLocation: 'assets/i18n',\n fileNames: {},\n apiUrl: null,\n appId: null,\n appToken: null,\n});\n```\n\nIt accepts an ITranslatorOptions options object with the following parameters:\n\n```ts\ninterface ITranslatorOptions {\n /** Allowed languages array, if found language is not in this array, will fall back to default, defaults `['en']` */\n availableLangs?: string[];\n /** The default language to select when the selected one is not found in availableLangs, defaults `'en'` */\n defaultLanguage?: string;\n /** Will take precedence over navigator language, defaults `'null'` */\n userLanguage?: string;\n /** Show missing translations in console, defaults `false` */\n isShowMissing?: boolean;\n /** Allow the use of cookie `lang` to save the language and localstorage to save translations and versions, defaults `false` */\n isLocalValuesAllowed?: boolean;\n /**\n * Enables attribute translations. This is less performant than tag option because it has to traverse and observe all DOM\n * to be reactive to changes. Defaults `false`\n */\n isEnableAttr?: boolean;\n /** The tags to filter strings when downloading translations, defaults `[]` */\n tags?: string[];\n /** The tag that will be sent to server when missing string is found, defaults `'app'` */\n missingTag?: string;\n /**\n * Path to the location of assets files, defaults `'assets/i18n'`. Alternatively a json in the form:\n * ```json\n * {\n * 'versions.json': { },\n * 'all.json': { 'key': 'translation', ... },\n * 'all-en.json': { 'key': 'translation', ... }\n * }\n */\n assetsLocation?: string | { [key: string]: { [key: string]: string } };\n /**\n * Names of the translations and version files. Examples of use:\n * ```\n * { \"--\": \"filename1.json\", \"ca\": \"filename2.json\", \"en\": \"filename3.json\", ..., \"versions\": \"filename.json\" }\n * ```\n * defaults: For every language, the default file is located at `all-${langCode}.json`:\n * ```\n * { \"--\": \"all.json\", \"ca\": \"all-ca.json\", \"en\": \"all-en.json\", ..., \"versions\": \"versions.json\" }\n * ```\n */\n fileNames?: { [key: string]: string };\n /** Api url to get remote updates from blablatec.com, defaults `null` */\n apiUrl?: string;\n /** App id to get remote updates from blablatec.com, defaults `null` */\n appId?: string;\n /** App token to get remote updates from blablatec.com, defaults `null` */\n appToken?: string;\n /** *EXPERIMENTAL*: When using a custom component, it defines the tag name, defaults `'i18n-babel'` */\n tagName?: string;\n /** *EXPERIMENTAL*: When using a custom component, it defines the target to translate, defaults `innerHTML'` */\n dataTarget?: string;\n /** *EXPERIMENTAL*: When using a custom component, it defines the attribute name for intetrpolation options, defaults `'data-i18n'` */\n dataAttribute?: string;\n /** Left stopper for interpolation, ie. `${myVariable}` would define '${' as left and '}' as right, defaults '${' */\n interpolateLeft?: string;\n /** Right stopper for interpolation, ie. `${myVariable}` would define '${' as left and '}' as right, defaults '}' */\n interpolateRight?: string;\n}\n```\n\n### `getInstance() => Translator`\n\nTranslator is a static object.\n\n- **returns**: an instance to the `Translator` object\n\n```js\nconst translator = Translator.getInstance();\n```\n\n### `setLocalValuesAllowed(isLocalValuesAllowed = false) => void`\n\nOpts in/out the use of local values.\n\n- `isLocalValuesAllowed` boolean value indicating if local values are allowed or not\n\n**WARNING**: calling this function with `false` will remove all local values.\n\n```js\nTranslator.setLocalValuesAllowed(true);\n```\n\n### `t(originalText: string, tData?: TypeTData, lang?: string) => Promise