README.md

_jsLingui

Seamless internationalization in Javascript and React

---

📖 Documentation

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 (might 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

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:

i18n._(
  'Hello, my name is {name}', 
  { values: { name } }
)

… you simply write:

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

---

Complex plural rules:

i18n._(
  `{numBooks, plural, 
    one {{name} has # book} 
    other {{name} has # books}}`, 
  { values: { name, numBooks } }
)

… becomes readable and type-checked:

i18n.plural({ 
  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:

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

… works seamlessly:

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

---

Messages with plurals:

<Trans 
    id="msg.plural" 
    defaults="{numBooks, plural, one{{name} has # book} other{{name} has # books}}"
    values={{ numBooks }}
/>

… are type-checked and errorproof:

<Plural 
  id="msg.plural"
  value={numBooks}
  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 = () => (
  <div>
    // Variable Interpolation
    <Trans>Hello {name}</Trans>
    
    // Seamless translations with components
    <Trans>
      Read the <Link to="/docs">documentation</Link>.
    </Trans>
    
    // Plurals
    <Plural 
      value={numBooks}
      one={<Trans>{name} has # book</Trans>}
      other={<Trans>{name} has # books</Trans>}
    />
  </div>
)

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:

<Plural 
  id="msg.plural"
  value={numBooks}
  one={<Trans>{name} has # book</Trans>}
  other={<Trans>{name} has # books</Trans>}
/>

Works anywhere

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

Contributors

Thanks goes to these people (emoji key):

Tomáš Ehrlich 💻 📖 💡 ✅	Josef Hornych 📖 🐛	Christian Kaps 🐛	brunesto 💻 🐛	David Furlong 💬

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

License

MIT