{"id":19692967,"url":"https://github.com/devbridge/reword-js","last_synced_at":"2025-04-29T09:31:34.267Z","repository":{"id":33843043,"uuid":"156542455","full_name":"devbridge/reword-js","owner":"devbridge","description":"reword-js","archived":false,"fork":false,"pushed_at":"2023-01-04T17:21:46.000Z","size":4892,"stargazers_count":11,"open_issues_count":10,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-19T08:14:43.580Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/devbridge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-07T12:21:46.000Z","updated_at":"2023-07-23T20:08:31.000Z","dependencies_parsed_at":"2023-01-15T02:54:31.781Z","dependency_job_id":null,"html_url":"https://github.com/devbridge/reword-js","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbridge%2Freword-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbridge%2Freword-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbridge%2Freword-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbridge%2Freword-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devbridge","download_url":"https://codeload.github.com/devbridge/reword-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251473321,"owners_count":21595038,"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":[],"created_at":"2024-11-11T19:14:53.425Z","updated_at":"2025-04-29T09:31:33.342Z","avatar_url":"https://github.com/devbridge.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# reword-js \u0026middot; ![GitHub release](https://img.shields.io/github/release/devbridge/reword-js.svg) ![CircleCI branch](https://img.shields.io/circleci/project/github/devbridge/reword-js/master.svg) ![David](https://img.shields.io/david/dev/devbridge/reword-js.svg) ![GitHub issues](https://img.shields.io/github/issues-raw/devbridge/reword-js.svg) ![GitHub](https://img.shields.io/github/license/devbridge/reword-js.svg) ![GitHub stars](https://img.shields.io/github/stars/devbridge/reword-js.svg?style=social\u0026label=Stars)\n\n**reword-js** is a zero dependency, minimal translation library written in JavaScript. Working in the browser and nodejs applications, **reword-js** provides an easy way to translate texts either by key or text content, with possibility to add dynamic parameters.\n\n# Installation\n\nvia [npm](https://www.npmjs.com/)\n\n`$ npm install reword-js`\n\nvia [yarn](https://yarnpkg.com/lang/en/)\n\n`$ yarn add reword-js`\n\n# Usage\n\nAs a node module\n\n```js\nconst reword = require('reword-js');\n\nreword.config(\n  {\n    /* ...dictionary */\n  },\n  {\n    /* ...options */\n  }\n);\n\nreword.translate`Default language text`; // translated language text\nreword.translateKey('someKey'); // translated language text\n```\n\nAs an ecmascript module\n\n```js\nimport { config, translate, translateKey } from 'reword-js';\n\nconfig(\n  {\n    /* ...dictionary */\n  },\n  {\n    /* ...options */\n  }\n);\n\ntranslate`Default language text`; // translated language text\ntranslateKey('someKey'); // translated language text\n```\n\nAs a script tag\n\n```html\n\u003c!DOCTYPE html\u003e\n\n\u003chtml lang=\"en\"\u003e\n  \u003chead\u003e \u003c/head\u003e\n\n  \u003cbody\u003e\n    \u003cscript src=\"\u003cpath-to-the-module\u003e/reword.umd.js\"\u003e\u003c/script\u003e\n    \u003cscript type=\"text/javascript\"\u003e\n      reword.config(\n        {\n          /* ...dictionary */\n        },\n        {\n          /* ...options */\n        }\n      );\n\n      reword.translate`Default language text`; // translated language text\n      reword.translateKey('someKey'); // translated language text\n    \u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n# Initialization\n\nReword can be used as a global instance, or separate instances created manually.\n\nExample:\n\n```js\nimport { Dictionary, config } from 'reword-js';\n\n//initialize as a standalone instance\nconst reword = new Dictionary(dictionary, options);\n\n//initialize as a global instance\nconfig(dictionary, options);\n```\n\n# Translation\n\nTranslating text can be acomplished in two ways. Either by key or by actual text. Reasoning behind text translation is that we have a natural fallback if translation key does not exist, interpolation also works just like a plain string which is more easier to read. Key translation is implemented for convenience as it is commonly used throughout other packages/languages.\n\nExample:\n\n```js\nimport { translate, translateKey } from 'reword-js';\n\nconst dictionary = {\n  'en-US': {\n    example: 'Translated language text'\n  },\n  'xx-XX': {\n    example: 'Translated other language text'\n  }\n};\n\nconfig(dictionary, { locale: 'xx-XX' });\n\n// Translate by text.\nreword.translate`Translated language text`; // Translated language text\n\n// Translate by key.\nreword.translateKey('example'); // Translated other language text\n```\n\n# Interpolation\n\nAdding dynamic values to translations is as easy as adding them to a hard coded string. Reword will also change variable order if the destination language has them ordered differently.\n\nExample:\n\n```js\nimport { translate, translateKey, config } from 'reword-js';\n\nconst dictionary = {\n  'en-US': {\n    example: 'Text with param {one} and param {two}'\n  },\n  'xx-XX': {\n    example: 'Text replaced with param {two} and param {one}'\n  }\n};\n\nconfig(dictionary, { locale: 'xx-XX' });\n\nconst one = 'Foo';\nconst two = 'Bar';\n\n// Text based translation\ntranslate`Text with param ${one} and param ${two}`; // Text replaced with param Bar and param Foo\n\n// Key based translation\ntranslateKey('example', one, two); // Text replaced with param Bar and param Foo\n```\n\n# Dictionary object\n\nDictionary is the primary object that holds all of the languages and translations. Must include a default language (see options object) and at least one of the translations. dictionary object can be nested as well.\n\nExample:\n\n```js\nconst dictionary = {\n  // Default language which is specified in options\n  'en-US': {\n    example: 'Translated language text',\n    nested: {\n      example: 'Translated nested language text'\n    }\n  },\n  // One or more languages with coresponding keys.\n  'xx-XX': {\n    example: 'Translated other language text',\n    nested: {\n      example: 'Translated nested other language text'\n    }\n  }\n};\n```\n\n# Options object\n\n`config` or `Dictionary` instance accepts an `options` object, which is shallow merged with the default options:\n\n- `defaultLocale`: Sets base locale for reword all of the translations are based on the default language (defaults to `en-US`)\n- `locale`: Sets initial locale so reword know which is the destination language (defaults to `en-US`)\n- `variableMatcher`: Regular expression pattern which identifies variables for interpolation (defaults to `/\\{(.*?)\\}/g`)\n- `translationNotFoundMessage`: Content display when a translation is not found. Only applies when translating by key. (defaults to `TRANSLATION_NOT_FOUND`)\n- `debug`: Debugging option which provides information on missing translations/parameters see [Debugging](#debugging). (defaults to `production` when used as a `umd` module and respects `process.env.NODE_ENV` while using `cjs` or `es` modules)\n\nExample:\n\n```js\nimport { Dictionary, config } from 'reword-js';\n\nconst dictionary = {};\nconst options = {\n  defaultLocale: 'en-US', // defaults to en-US\n  locale: 'es-ES'\n  variableMatcher: /\\{(.*?)\\}/g,\n  translationNotFoundMessage: 'Could not find any key to translate'\n  debug: true // or false\n};\n\n// Using with global instance\nconfig(dictionary, options)\n\n// Using with dedicated instance\nconst translations = new Dictionary(dictionary, options);\n```\n\n# API Reference\n\nReword public instance is initialized on module import thus contains all of the methods described in the api refrence.\n\n### `Dictionary.prototype.config(dictionary, options)`\n\nWorks like a constructor method, used to re-initialize the dictionary.\n\n### `Dictionary.prototype.changeLocale(localeString)`\n\nChanges destination language to a desired one.\n\n### `Dictionary.prototype.updateDictionary(dictionary)`\n\nOverwrites dictionary with a new one. Does not update any options.\n\n### `Dictionary.prototype.translate(string, [...parameters])`\n\nCan be called as template string or as a regular function.\n\n```js\nconst translateString = `String with {numberOfParams}`;\n\ntranslate`String with ${numberOfParams}`;\n\ntranslate(translateString, numberOfParams);\n```\n\n### `Dictionary.prototype.translateKey(key, [...parameters])`\n\nA dictionary key can be provided to translate via key instead of text. If no key was found it will show text defined in the options object see [Options object](#options-object)\n\n```js\ntranslateKey('example'); // Translated text is returned;\n\ntranslateKey('example', param1, param2); // Translated text with parameters returned;\n```\n\n# Debugging\n\n**reword-js** provides some debugging capabilities if `debug` option is enabled. see [Options object](#options-object).\n\n## Console warning\n\nIf translation is not found **reword-js** will throw a `console.warn` message.\n\nExample:\n\n![some](https://github.com/devbridge/reword-js/raw/master/gifs/warnings.gif)\n\n## Console table\n\nWhen loading up dictionary it's being validated and outputs information on what's missing.\n\nExample:\n\n![some](https://github.com/devbridge/reword-js/raw/master/gifs/table.gif)\n\n# Integration\n\n## React application\n\nSince **reword-js** is not tied to the state or store in react applications, thus it does not trigger a re-render. The easiest way is to trigger a re-render when language changes is by setting a `key` prop on the top most component in your React application. Once the key changes, React will re-render the DOM tree underneath.\n\nExample:\n\n```js\nimport React, { PureComponent } from 'react';\nimport { config, translate, changeLocale } from 'reword-js';\n\nclass App extends PureComponent {\n  constructor() {\n    super();\n    config({}, { locale: this.state.locale });\n  }\n\n  state = {\n    locale: 'en-US'\n  };\n\n  changeLanguage = ({ target }) =\u003e {\n    changeLocale(target.value);\n    this.setState({\n      locale: target.value\n    });\n  };\n\n  render() {\n    return (\n      \u003cdiv key={this.state.locale}\u003e\n        \u003cbutton onClick={this.changeLanguage} value=\"en-US\"\u003e\n          English\n        \u003c/button\u003e\n        \u003cbutton onClick={this.changeLanguage} value=\"es-ES\"\u003e\n          Spanish\n        \u003c/button\u003e\n        {translate`Translated text`}\n      \u003c/div\u003e\n    );\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevbridge%2Freword-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevbridge%2Freword-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevbridge%2Freword-js/lists"}