i18n-react

by alexdrel

alexdrel / i18n-react

React (JS) text internationalization and externalizing

129 Stars 17 Forks Last release: over 1 year ago (release/0.7.0) MIT License 37 Commits 10 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Build Status

i18n-react

React (JS) text internationalization and externalizing. Markdown-ish syntax with variables support (including of react element type).

Quick example

var ReactDOM = require('react-dom');
var React = require('react');
const { MDText } = require('i18n-react');

const T = new MDText({ greeting: "#Hello, World!\n My name is {myName}! \n {{howAreYou}}", howAreYou: "How do you do?" }, { MDFlavor: 1 });

ReactDOM.render( <t.span text="{{" key: myname:></t.span>, document.getElementById('content') );

Unsurprisingly renders:


Hello, World!

My name is i18n-react!

How do you do?


External yaml resource file

Usually texts are retrived from an extrenal source (I would recommend YAML format) but loading of the external files is out of scope for the library.

greetings:
  hello: Hi, {who}!
  howdy:
    formal: How do you do?
    normal: How are you, {who}?
    informal: "What's up?"
  bye: Bye

longTime: 0: Not a day no see 1: 1 day no see '2..4': A few days no see _: "[{context} days][Long time no see]"

Points of interest: * {who} - variable interpolation * formal/informal - context selectors * longTime - pluralization and range * [X days][...] - renders two paragraphs

Usage

Npm compatible packager (browserify/webpack) is recommended, but

Dist
folder also contains UMD versions (regular and minified) that can be used w/o commonJS packager.

Global Singleton

/* ES6 & TS */
import T from 'i18n-react';
/* commonJS */
var T = require('i18n-react').default;
/* when using UMD version w/o modules */
var T = window['i18n-react'].default;

Setup once - probably in an application entry point js:

js
T.setTexts({
  greeting: "Hello, World! My name is *{myName}*! \n {{howAreYou}}",
  howAreYou:  "_How do you do?_"
}, { MDFlavor: 0 });
/* or if there is yaml/json loader */
var dictionary = require('../texts/texts-en.yml');
T.setTexts(dictionary);

Use it anywhere:

xml
 
 
 
 X}}/>
 

{T.translate("path.to.string", { context: "context", val: 1})}

Creating new MDText object

In case you want to control lifecycle of the dictionary object (instead of default singleton) it can be created with MDText constructor.

js
import { MDText } from 'i18n-react';
let T = new MDText({...});
let x = T.translate("path.to.string");

Passing in the React Context

MDText object can be passed in the react 16.3+ context. See examples/yaml for complete example. ```tsx import { MDText } from 'i18n-react'; let MDTextContext = React.createContext(); let Texts = new MDText({...});

{ (T) => } ```

Difference between Keys and Context

Text attribute is a key that should point to string or JSON object, it has to be present in the language resource. Then if needed the context is used to disambiguate betwen multiple texts according to the following rules: 1. Exact match for the context value. 1. For numeric context values - key with range, e.g. 2..4 that matches context value. 1. Explicit default - '_' key. 1. First key.

Missing translations

By default if translation for the specified key is not present the key itself is returned to help you find the missing translation. This behaviour can be augmented by passing custom

notFound
value to setText options or MDText contructor.

This value can be either a string, or a function returning a string. If it is a string, then it will be returned as is any time a key is missing. If you provide a function, then the function will be run with the missing key and context as arguments.

// "Not Found!" will replace all missing translations
T.setTexts(translations, {
  notFound: 'Not Found!'
})

// "SomeKey ${key} ${key}` // will render SomeKey })

Function in translation

Translation dictionaries can be extended with functions (as in notFound).

T.setTexts({
    a: 'A',
    n: (_key, ctx) => ctx ? `Number ${ctx}` : '',
  });
T.translate('a')) // 'A'
T.translate('n', { context: 9 })) // 'Number 9'

Markdown syntax

  • *italic*
    italic -
    breaking change V1,
    in V0
  • _italic_
    italic -
    breaking change V1,
    in V0
  • **bold**
    bold
    new - V1
  • __bold__
    bold
    new - V1
  • ~underlined~
    underlined
    new - V1
  • ~~strike~~
    ~~strike~~
    new - V1
  • \n
    New Line

  • [Paragraph 1][Paragraph 2]
    Multiple paragraphs

  • #
    -
    ####
    Headers

    -

  • `` *as*_[IS]_ `` Literal new - V1

Unit tests are half-loaf documentation

You are welcomed to consult examples folder and unit tests for usage details and examples.

Breaking changes

0.7

Literal `` changed to better match GitHub

Allows matching number of backticks (with optional whitespace) to form a literal. This allows quoting of the backtick pairs:

``` `` ```
=>
``
.

0.6

Literal `` in V1 syntax

New `` syntax `` (in V1 only) to disable MD processing.

0.5

React 16+ required

As React now allows fragments and strings in render the default behavior of

 changed not to wrap the output into 
when
tag
property is not specified.

0.4

New MD syntax

The new MD flavor (aligned with github's Markdown) is added : V1. Opt-in for this release, will become default in the next major release. V1 introduces strike and underline, and rehabilitates

and
tags.
  em: "an *italic* style"
  i: "an _italic_ style"
  strong: "a **bold** move"
  b: "a __bold__ move"
  u: "an ~underlined~ word"
  strike: "a ~~strike~~ out"

To opt-in for the new syntax:

js
let T = new MDText(texts, { MDFlavor: 1 });
// or for the singelton
T.setTexts(require('../texts/texts-en.yml'), { MDFlavor: 1, notFound: 'NA' });

notFound Deprecation

MDText notFound property is deprecated - please switch to constructor or serTexts options.

0.3

Unknown Prop Warning

React 15.2 is preparing to stop filtering HTML properties (https://fb.me/react-unknown-prop) - the feature that i18n relied upon for preventing interpolation variables from leaking into the DOM.

Thus new syntax for passing variables is introduced:

xml

/* replaces */

All tags passing to T.* anything beside
text
,
tag
and
context
properties have to be updated or React 15.2 will cry annoyingly.
typescript 2.0 / [email protected] typings

Updated package.json contains all the info for the new typescript to get typings automatically.

0.2

  • ES6 style export (use default export explicitly for commonJS/UMD)
  • Stateless react components (shouldComponentUpdate optimization removed)
  • Default export (T above) no longer can be used as a react component (use T.text or T.span instead)

Development

Commands

  • Watch commonJS build:
    $ npm start
  • Build commonJS/UMD version:
    $ npm run build
  • Start dev server for examples:
    $ npm run examples
    (http://localhost:1818/webpack-dev-server/examples/)
  • Build examples:
    $ npm run build:examples
  • Run tests (Firefox):
    $ npm test
  • Watch tests (Chrome):
    $ npm run test:watch

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.