{"id":23569173,"url":"https://github.com/alexdrel/i18n-react","last_synced_at":"2025-07-02T11:37:09.348Z","repository":{"id":57270360,"uuid":"39280596","full_name":"alexdrel/i18n-react","owner":"alexdrel","description":"React (JS) text internationalization and externalizing","archived":false,"fork":false,"pushed_at":"2020-05-22T07:44:22.000Z","size":269,"stargazers_count":133,"open_issues_count":0,"forks_count":15,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T06:07:55.152Z","etag":null,"topics":["i18n","markdown","react"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/alexdrel.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2015-07-18T00:10:48.000Z","updated_at":"2024-12-16T03:50:54.000Z","dependencies_parsed_at":"2022-09-05T00:02:05.724Z","dependency_job_id":null,"html_url":"https://github.com/alexdrel/i18n-react","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdrel%2Fi18n-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdrel%2Fi18n-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdrel%2Fi18n-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdrel%2Fi18n-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexdrel","download_url":"https://codeload.github.com/alexdrel/i18n-react/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247615385,"owners_count":20967184,"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":["i18n","markdown","react"],"created_at":"2024-12-26T19:12:51.108Z","updated_at":"2025-04-07T08:20:33.803Z","avatar_url":"https://github.com/alexdrel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/alexdrel/i18n-react.svg?branch=master)](https://travis-ci.org/alexdrel/i18n-react)\n\ni18n-react\n===\nReact (JS) text internationalization and externalizing.\nMarkdown-ish syntax with variables support (including of react element type).\n\n### Quick example\n\n```js\nvar ReactDOM = require('react-dom');\nvar React = require('react');\nconst { MDText } = require('i18n-react');\n\nconst T = new MDText({\n  greeting: \"#Hello, World!\\n My name is **{myName}**! \\n {{howAreYou}}\",\n  howAreYou:  \"_How do you do?_\"\n}, { MDFlavor: 1 });\n\nReactDOM.render(\n  \u003cT.span text={{ key: \"greeting\", myName: \"i18n-react\" }}/\u003e,\n  document.getElementById('content')\n);\n```\n\nUnsurprisingly renders:\n********\n### Hello, World!\nMy name is **i18n-react**!\n\n_How do you do?_\n\n********\n\n### External yaml resource file\nUsually texts are retrived from an extrenal source (I would recommend YAML format) but\nloading of the external files is out of scope for the library.\n\n```yaml\ngreetings:\n  hello: Hi, {who}!\n  howdy:\n    formal: How do you do?\n    normal: How are you, {who}?\n    informal: \"What's up?\"\n  bye: Bye\n\nlongTime:\n  0: Not a day no see\n  1: 1 day no see\n  '2..4': A few days no see\n  _: \"[{context} days][Long time no see]\"\n```\n\nPoints of interest:\n* {who} - variable interpolation\n* formal/informal - context selectors\n* longTime - pluralization and range\n* [X days][...] - renders two paragraphs\n\n\n## Usage\nNpm compatible packager (browserify/webpack) is recommended, but ```Dist``` folder also contains UMD versions\n(regular and minified) that can be used w/o commonJS packager.\n\n### Global Singleton\n```js\n/* ES6 \u0026 TS */\nimport T from 'i18n-react';\n/* commonJS */\nvar T = require('i18n-react').default;\n/* when using UMD version w/o modules */\nvar T = window['i18n-react'].default;\n```\n\n\nSetup once - probably in an application entry point js:\n```js\nT.setTexts({\n  greeting: \"Hello, World! My name is *{myName}*! \\n {{howAreYou}}\",\n  howAreYou:  \"_How do you do?_\"\n}, { MDFlavor: 0 });\n/* or if there is yaml/json loader */\nvar dictionary = require('../texts/texts-en.yml');\nT.setTexts(dictionary);\n```\n\nUse it anywhere:\n```xml\n \u003cT.a text=\"path.to.string\" href=\"a's href\"/\u003e\n \u003cT.text tag='h1' text=\"path.to.string\" context: \"context-if-any\"/\u003e\n \u003cT.p text={{ key: \"path.to.string\", var1: \"string\", var2: 2}} anyValidHtmlAttribute=\"p.will.have.it\"/\u003e\n \u003cT.span text={{ key: \"path.to.string\", context: \"context-if-any\", var1: \"string\", var2: 2, var3: \u003cspan className=\"c\"\u003eX\u003c/span\u003e}}/\u003e\n \u003ch1\u003e{T.translate(\"path.to.string\", { context: \"context\", val: 1})}\u003c/h1\u003e\n```\n\n### Creating new MDText object\nIn case you want to control lifecycle of the dictionary object (instead of default singleton)\nit can be created with MDText constructor.\n```js\nimport { MDText } from 'i18n-react';\nlet T = new MDText({...});\nlet x = T.translate(\"path.to.string\");\n\u003cT.span text=\"path.to.string\" /\u003e\n```\n### Passing in the React Context\nMDText object can be passed in the react 16.3+ context. See examples/yaml for complete example.\n```tsx\nimport { MDText } from 'i18n-react';\nlet MDTextContext = React.createContext();\nlet Texts = new MDText({...});\n\n\u003cMDTextContext.Provider value={Texts}\u003e\n    \u003cMDTextContext.Consumer\u003e{ (T) =\u003e\n      \u003cT.span text=\"path.to.string\" /\u003e\n    }\u003c/MDTextContext.Consumer\u003e\n\u003c/MDTextContext.Provider\u003e\n```\n\n### Difference between Keys and Context\nText attribute is a key that should point to string or JSON object, it has to be present in the language resource.\nThen if needed the context is used to disambiguate betwen multiple texts according to the following rules:\n1. Exact match for the context value.\n1. For numeric context values - key with range, e.g. 2..4 that matches context value.\n1. Explicit default - '_' key.\n1. First key.\n\n### Missing translations\nBy default if translation for the specified key is not present the key itself is returned\nto help you find the missing translation.\nThis behaviour can be augmented by passing custom ``notFound`` value to setText options or MDText contructor.\n\nThis value can be either a string, or a function returning a string.\nIf it is a string, then it will be returned as is any time a key is missing.\nIf you provide a function, then the function will be run with the missing key\nand context as arguments.\n\n```js\n// \"Not Found!\" will replace all missing translations\nT.setTexts(translations, {\n  notFound: 'Not Found!'\n})\n\n// \"SomeKey \u003c-- this guy\" will appear instead\nT.setTexts(translations, {\n  notFound: key =\u003e `${key} \u003c-- this guy`\n})\n\n// you can combine this solution with markdown!\nT.setTexts(translations, {\n  notFound: key =\u003e `**${key}**` // will render \u003cstrong\u003eSomeKey\u003c/strong\u003e\n})\n```\n\n### Function in translation\nTranslation dictionaries can be extended with functions (as in notFound).\n\n```js\nT.setTexts({\n    a: 'A',\n    n: (_key, ctx) =\u003e ctx ? `Number ${ctx}` : '',\n  });\nT.translate('a')) // 'A'\nT.translate('n', { context: 9 })) // 'Number 9'\n```\n\n## Markdown syntax\n\n + ``*italic*`` *italic*  - ``\u003cem\u003e`` **breaking change V1, ``\u003cstrong\u003e`` in V0**\n + ``_italic_`` _italic_  - ``\u003ci\u003e`` **breaking change V1, ``\u003cem\u003e`` in V0**\n + ``**bold**`` **bold** ``\u003cstrong\u003e`` *new - V1*\n + ``__bold__`` __bold__ ``\u003cb\u003e`` *new - V1*\n + ``~underlined~`` \u003cu\u003eunderlined\u003c/u\u003e ``\u003cu\u003e`` *new - V1*\n + ``~~strike~~`` ~~strike~~  ``\u003cstrike\u003e`` *new - V1*\n + ``\\n`` New Line ``\u003cbr\u003e``\n + ``[Paragraph 1][Paragraph 2]`` Multiple paragraphs ``\u003cp\u003e``\n + ``#``-``####`` Headers ``\u003ch1\u003e-\u003ch4\u003e``\n + \\`\\` \\*as\\*\\_[IS]\\_ \\`\\`  Literal  *new - V1*\n\n### Unit tests are half-loaf documentation\nYou are welcomed to consult examples folder and unit tests for usage details and examples.\n\n## Breaking changes\n### 0.7\n##### Literal \\`\\` changed to better match GitHub\nAllows matching number of backticks (with optional whitespace) to form a literal. This allows quoting of the  backtick pairs: ```` ``` `` ``` ```` =\u003e ``` `` ``` .\n\n### 0.6\n##### Literal \\`\\` in V1 syntax\nNew \\`\\` syntax  \\`\\` (in V1 only) to disable MD processing.\n\n### 0.5\n##### React 16+ required\nAs React now allows fragments and strings in render the default behavior of ``\u003cT.text\u003e`` changed not to wrap the output into ``\u003cspan\u003e`` when ``tag`` property is not specified.\n\n### 0.4\n##### New MD syntax\nThe new MD flavor (aligned with github's Markdown) is added : V1. Opt-in for this release, will become default in the next major release.\nV1 introduces strike and underline, and rehabilitates ``\u003cb\u003e`` and ``\u003ci\u003e`` tags.\n\n```yaml\n  em: \"an *italic* style\"\n  i: \"an _italic_ style\"\n  strong: \"a **bold** move\"\n  b: \"a __bold__ move\"\n  u: \"an ~underlined~ word\"\n  strike: \"a ~~strike~~ out\"\n```\nTo opt-in for the new syntax:\n```js\nlet T = new MDText(texts, { MDFlavor: 1 });\n// or for the singelton\nT.setTexts(require('../texts/texts-en.yml'), { MDFlavor: 1, notFound: 'NA' });\n```\n#### notFound Deprecation\nMDText notFound property is deprecated - please switch to constructor or serTexts options.\n\n### 0.3\n##### Unknown Prop Warning\nReact 15.2 is preparing to stop filtering HTML properties (https://fb.me/react-unknown-prop) - the feature that i18n relied upon for\npreventing interpolation variables from leaking into the DOM.\n\nThus new syntax for passing variables is introduced:\n```xml\n\u003cT.span text={{ key: \"greeting\", myName: \"i18n-react\" }}/\u003e\n/* replaces */\n\u003cT.span text=\"greeting\" myName=\"i18n-react\"/\u003e\n```\nAll tags passing to T.* anything beside ```text```, ```tag``` and ```context``` properties have to be updated or React 15.2 will cry annoyingly.\n\n##### typescript 2.0 / ts@next typings\nUpdated package.json contains all the info for the new typescript to get typings automatically.\n\n### 0.2\n* ES6 style export (use default export explicitly for commonJS/UMD)\n* Stateless react components (shouldComponentUpdate optimization removed)\n* Default export (T above) no longer can be used as a react component (use T.text or T.span instead)\n\n## Development\n#### Commands\n* Watch commonJS build:  ```$ npm start```\n* Build commonJS/UMD version:  ```$ npm run build```\n* Start dev server for examples: ```$ npm run examples``` (http://localhost:1818/webpack-dev-server/examples/)\n* Build examples: ```$ npm run build:examples```\n* Run tests (Firefox): ```$ npm test```\n* Watch tests (Chrome): ```$ npm run test:watch```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdrel%2Fi18n-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexdrel%2Fi18n-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdrel%2Fi18n-react/lists"}