bs1180 / js-lingui

Seamless i18n in Javascript and React

Home Page:

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool


Seamless internationalization in Javascript and React

Join the chat at CircleCI Code Coverage PRs Welcome All Contributors MIT License

Watch on GitHub Star on GitHub Tweet

πŸ“– Documentation

πŸ“¦ Migrating to 2.x

Type-checked and intuitive way to internationalize applications in Javascript and React.

Internationalization is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language.

--- W3C Web Internationalization FAQ

Key features

  • Small and fast - about 6kb gzipped
  • Babel plugin for convenient, type-checked way of writing ICU MessageFormat (recommended, but not required)
  • CLI for extracting and compiling message catalogs
  • Built on standard ICU MessageFormat (is able to replace react-intl completely)
    • Variable interpolation
    • Components inside translations (e.g: Read <Link to="...">documentation</Link>.)
    • Plurals, Ordinals and Categories (i.e. Select)
    • Number and Date formats (from Intl)
  • Works with manual and generated message IDs
  • Works with in any JS environment, while integration packages brings better performance in target environments (e.g: lingui-react for React)
  • High quality build (high test coverage, follows semver, deprecation warnings for breaking changes and migration guides for major releases)

See the tutorial for React

Example use case with React

Intuitive way of writing messages

No matter what i18n library you use, there is always an underlying message format that handles variable interpolation, plurals and date/number formatting. js-lingui isn't reinventing the wheel, but rather uses standardized ICU MessageFormat which is supported in many platforms (the same format that react-intl uses).

js-lingui goes one step further and allows you to write messages in a way so intuitive that you'll forget there's an underlying i18n library.

Compare following examples of low-level API and convenient functions/components:

Instead of:

  'Hello, my name is {name}', 
  { name }

… you simply write:

i18n.t`Hello, my name is ${name}`

Complex plural rules:

  `{numBooks, plural, 
    one {{name} has # book} 
    other {{name} has # books}}`, 
  { name, numBooks }

… becomes readable and type-checked:

  value: numBooks, 
  one: `${name} # book`, 
  other: `${name} # books`

The same message in React:

<Trans id="msg.simple" defaults="Hello {name}" values={{ name }} />

… becomes:

<Trans id="msg.simple">Hello {name}</Trans>

Components inside translations:

    defaults="Read the <0>documentation</0>."
    components={[<Link to="/docs" />]}

… works seamlessly:

<Trans id="">
  Read the <Link to="/docs">documentation</Link>.

Messages with plurals:

    defaults="{numBooks, plural, one{{name} has # book} other{{name} has # books}}"
    values={{ numBooks }}

… are type-checked and errorproof:

  one={<Trans>{name} has # book</Trans>}
  other={<Trans>{name} has # books</Trans>}

Note: In examples above, the first example is low-level API which you can use when babel plugin isn't available (e.g. in Create React Apps). However, you'll miss another layer of validation and type-checking for messages.

Message IDs are optional. Without them it's even easier, default messages become message ids:

const Pitch = () => (
    // Variable Interpolation
    <Trans>Hello {name}</Trans>
    // Seamless translations with components
      Read the <Link to="/docs">documentation</Link>.
    // Plurals
      one={{name} has # book}
      other={{name} has # books}

Batteries included - CLI for working with message catalogs

js-lingui ships with easy CLI for extracting, merging and compiling of message catalogs.

All messages from the source files can be extracted with one command:

lingui extract
Extracting messages from source files…
Collecting all messages…
Writing message catalogues…
Messages extracted!

Catalog statistics:
β”‚ Language β”‚ Total count β”‚ Missing β”‚
β”‚ cs       β”‚     42      β”‚   34    β”‚
β”‚ en       β”‚     42      β”‚   42    β”‚
β”‚ fr       β”‚     42      β”‚   42    β”‚

(use "lingui add-locale <language>" to add more locales)
(use "lingui extract" to update catalogs with new messages)
(use "lingui compile" to compile catalogs for production)

If you run this command second time, it'll merge translations from existing catalog with new messages.

Works with manual and generated message IDs

js-lingui doesn't force you to use generated message IDs either. If you prefer setting your IDs manually, just pass id prop. Generated message will be used as a default one:

  one={{name} has # book}
  other={{name} has # books}

Works anywhere

Core library @lingui/core works in any JS environment. Intergration libraries like @lingui/react only brings better performace for target environments.


Thanks goes to these people (emoji key):

TomΓ‘Ε‘ Ehrlich

πŸ’» πŸ“– πŸ’‘ βœ…

Josef Hornych

πŸ“– πŸ›

Christian Kaps



πŸ’» πŸ›

David Furlong



πŸ› πŸ“–

Sebastian SobociΕ„ski


This project follows the all-contributors specification. Contributions of any kind welcome!



ezoic increase your site revenue


Seamless i18n in Javascript and React

License:MIT License


Language:JavaScript 99.3%Language:Shell 0.7%