{"id":13658805,"url":"https://github.com/artkravchenko/t8on","last_synced_at":"2026-02-18T21:35:32.660Z","repository":{"id":65513778,"uuid":"93442536","full_name":"artkravchenko/t8on","owner":"artkravchenko","description":":fire: Manage, format and translate phrases easily","archived":false,"fork":false,"pushed_at":"2017-10-25T16:52:57.000Z","size":47,"stargazers_count":1,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-20T10:20:27.492Z","etag":null,"topics":["dictionary","i18n","l10n","language","lightweight","localization","translation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artkravchenko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-05T20:12:30.000Z","updated_at":"2022-06-13T14:36:21.000Z","dependencies_parsed_at":"2023-01-26T20:55:15.549Z","dependency_job_id":null,"html_url":"https://github.com/artkravchenko/t8on","commit_stats":null,"previous_names":["oopscurity/t8on"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artkravchenko%2Ft8on","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artkravchenko%2Ft8on/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artkravchenko%2Ft8on/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artkravchenko%2Ft8on/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artkravchenko","download_url":"https://codeload.github.com/artkravchenko/t8on/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250618676,"owners_count":21460136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dictionary","i18n","l10n","language","lightweight","localization","translation"],"created_at":"2024-08-02T05:01:02.779Z","updated_at":"2026-02-18T21:35:32.602Z","avatar_url":"https://github.com/artkravchenko.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# t8on\n\n`t8on` is a JavaScript library for managing sets of locales and both basic and customizable phrases in the application.\n\nIt's lightweight and useful enough at the same time, being able to run in various environments due to the power of [UMD](https://github.com/umdjs/umd).\n\n[![Build Status](https://travis-ci.org/Oopscurity/t8on.svg?branch=master)](https://travis-ci.org/Oopscurity/t8on) [![Coverage Status](https://coveralls.io/repos/github/Oopscurity/t8on/badge.svg?branch=master)](https://coveralls.io/github/Oopscurity/t8on?branch=master)\n\n___\n\n## Quick example\n\n```javascript\nt.loadRoot({\n  en: { welcome: 'Welcome, %0!', greeting_q: 'How do you do?' },\n  ru: { welcome: 'Добро пожаловать!' }\n});\n\nt.translate('welcome', 'ru');\n// =\u003e 'Добро пожаловать!'\n\nt.format('welcome', 'en', 'John');\n// =\u003e 'Hello, John!'\n\nconst toEnglish = t.translateTo('en');\ntoEnglish('greeting_q');\n// =\u003e 'How do you do?'\n```\n\nAlthough the library is simple, some details and convenient methods are missing in the example above. So it's recommended to read the following **\"Usage\"** section to learn how to configure and to use the library properly.\n\n## Usage\n\n`t8on` provides a storage to serve locales and phrases/translations pairs.\n\n### Load the storage\n\nThe storage is available as a singleton:\n\n```javascript\nimport t from 't8on';\n```\n\nIt also can be instantiated from `Translation` class manually.\n\n```javascript\nimport { Translation } from 't8on';\n\nconst t: Translation = new Translation();\n```\n\n### Get storage's current dictionary\n\nYou can get the link to the existing dictionary via `Translation#dictionary()` method. In our case it's empty:\n\n```javascript\nt.dictionary();\n// {}\n```\n\n### Load the dictionary or particular locales\n\nThe storage accepts dictionaries of the following type:\n\n```javascript\ntype Translations = {\n  [phrase: string]: string // translation\n};\n\ntype Dictionary = {\n  [locale: string]: Translations\n};\n\nconst initialDictionary: Dictionary = {\n  en: { greeting: 'Hello' }\n};\n\nconst dictionary: Dictionary = {\n  en: { welcome: 'Welcome' },\n  ru: { welcome: 'Добро пожаловать' }\n};\n```\n\nTo load the dictionary from root level, use `Translation#loadRoot(root: Dictionary): Translation`. It extends already present locales and translations. Note the method's (and few others') return value is current instance of `Translation`:\n\n```javascript\nt\n  .loadRoot(initialDictionary)\n  .dictionary();\n// =\u003e { en: { greeting: 'Hello' } }\n\nt\n  .loadRoot(dictionary);\n  .dictionary();\n/* =\u003e {\n    en: { greeting: 'Hello', welcome: 'Welcome' },\n    ru: { welcome: 'Добро пожаловать' }\n  }\n*/\n```\n\nTo load one locale, use `Translation#load(locale: string, pairs: Translations)`. Note that it extends existing locales, doesn't rewrite them.\n\n```javascript\nconst newPhrase = { greeting_q: 'How do you do?' };\n\nt\n  .load('en', newPhrase)\n  .dictionary();\n/* =\u003e {\n    en: {\n      greeting: 'Hello',\n      welcome: 'Welcome',\n      greeting_q: 'How do you do?'\n    },\n    ru: { welcome: 'Добро пожаловать' }\n  }\n*/\n```\n\nHowever, if you'd like to set the locale from scratch, deleting all the translations presented there, use `Translation#setLocale(locale: string, pairs: Translations)`:\n\n```javascript\nconst nextLocale = { welcome: 'Hello there!' };\n\nt\n  .setLocale('en', nextLocale);\n  .dictionary();\n/* =\u003e {\n    en: { welcome: 'Hello there!' },\n    ru: { welcome: 'Добро пожаловать' }\n  }\n*/\n```\n\n### Get the translation\n\nThere are two types of phrases/translations:\n\n- simple, such as listed above;\n- parameterized, like `'Hello, %0!'`.\n\nLet's start with simple ones.\n\n### Simple translations\n\nIn order to get a translation of given phrase, you can use several options:\n\n1. Set default locale name to `Translation#defaultLocale: string` for the whole instance of `Translation` and then call `Translation#translateCurrent(phrase: string)`.\n\n```javascript\nt.defaultLocale = 'en';\nt.translateCurrent('welcome');\n// =\u003e 'Hello there!'\n```\n\n**Important:** if there's no translation found, all `translate*` and `format*` functions translate the phrase to fallback locale if it's set with `Translation#fallbackLocale: string`. If the dictionary of fallback locale doesn't contain the phrase too, empty string `''` is returned.\n\n2. Create translation function to desired locale with `Translation#translateTo(locale: string)`. Call it with a phrase name to get the translation:\n\n```javascript\nconst toRussian: (phrase: string) =\u003e string = t.translateTo('ru');\ntoRussian('welcome');\n// =\u003e 'Добро пожаловать'\n```\n\n3. Use `Translation#translate(phrase: string, locale: string)`:\n\n```javascript\nt.translate('welcome', 'en');\n// =\u003e 'Hello there!'\n```\n\n### Parameterized translations\n\nSometimes, there are situations when you can't just translate the given phrase, you need to customize it smartly.\n\nParameterized translations accept one or more string arguments to manage more complex expressions. The parameters number to translate the phrase to each locale may differ. The numbering is zero based:\n\n```javascript\nconst parameterizedDictionary: Dictionary = {\n  en: {\n    set_default_q: 'Would you like to set %0 your default browser?'\n  },\n  ru: {\n    set_default_q: 'Не желаете ли Вы сделать %0 браузером по умолчанию?'\n  }\n};\n```\n\nThe same arguments can be included in the translation as many times as you wish. \n\n```javascript\n'I repeat the argument three times: %0! %0! %0!'\n```\n\nThey also can be mixed:\n\n```javascript\n'Your name reversed: %1 %0'\n```\n\nFinally, by analogy with `translate*` methods, you have 3 options in order to insert arguments to the translations. The operation is `format` based:\n\n1. \"Format\" phrases to the default locale with `Translation#formatCurrent(phrase: string, ...args: Array\u003cstring\u003e)`:\n\n```javascript\nt\n  .loadRoot(parameterizedDictionary)\n  .formatCurrent('set_default_q', 'Mozilla Firefox');\n// =\u003e 'Would you like to set Mozilla Firefox your default browser?'\n```\n\n2. Create formatting function to the given locale with `Translation#formatTo(locale: string)` and then use it directly:\n\n```javascript \nconst toRussian: (phrase: string, ...args: Array\u003cstring\u003e) =\u003e string = t.formatTo('ru');\ntoRussian('set_default_q', 'Google Chrome');\n// =\u003e 'Не желаете ли Вы сделать Google Chrome браузером по умолчанию?'\n```\n\n3. Use common `Translation#format(phrase: string, locale: string, ...args: Array\u003cstring\u003e)`:\n\n```javascript\nt.format('set_default_q', 'en', 'Vivaldi');\n// =\u003e 'Would you like to set Vivaldi your default browser?'\n```\n\n## Installation\n\nt8on is available as the [`t8on`](https://www.npmjs.com/package/t8on) package on [npm](https://www.npmjs.com/).\n\nTo install the latest stable version, type\n\n```\nnpm install --save t8on\n```\n\nYou can also access package's files on [unpkg.com](https://unpkg.com/t8on/).\n\nThe package provides a [CommonJS](https://webpack.js.org/api/module-methods/#commonjs) module in the `lib` directory and a production-ready [UMD](https://github.com/umdjs/umd) build in the `dist` folder.\n\nAlthough t8on is intended for usage with module bundlers such as [Webpack](https://webpack.js.org/), thanks to UMD, it's possible to use `t8on` with many other JavaScript module loaders or completely without them.\n\nIf it sounds like your case, you can simply connect the UMD build as a `\u003cscript\u003e` tag on the web page. After that, the library will be available via `window.t8on`.\n\n## Licence\n\n`t8on` is [MIT licensed](https://github.com/Oopscurity/t8on/blob/master/LICENSE).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartkravchenko%2Ft8on","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartkravchenko%2Ft8on","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartkravchenko%2Ft8on/lists"}