README

a18n

English | 中文

Automated I18n solution for JavaScript/TypeScript/React.

This lib wraps and extracts text in js/ts/jsx/tsx files using AST manipulation, making adding I18n support a breeze.

Features

CLI (for code modification):
- Wrap texts with translation calls (a18n wrap)
  
  Note: "Wrap" is only applied to CJK texts, so texts in English are not supported for now.
- Extract texts from translation calls (a18n extract)
- Check for untranslated text in code and resources (a18n check)
- Replace untranslated in code with translated ones (a18n replace)
- Purge remove translation calls and imports (a18n purge)
- Support dynamic texts in ES6 Template String
- Support TypeScript
- Support React, or any framework that uses JSX
- Ignore lines or files with annotation comments
- Preserves original code formatting while modifying code as much as possible (though prettier is still recommended)
API (for text translation):
- Translate static and dynamic texts using provided locale resource
- Tiny (~ 200 loc)
- Fast, dynamic texts are compiled into template at first run

Getting Started

WARNING: existing project code will be modified, backup or commit before proceed

Install as dependency (not devDependency, as a18n provides both CLI and runtime)

cd that_legacy_codebase
npm install --save a18n

Scan and modify code files (.js, .ts, .jsx, .tsx) in src directory, this will wrap CJK text strings with translation calls:

npx a18n wrap src --write

Manually check for unintended modifications and fix them, you can:

use comment // @a18n-ignore to ignore next line
use comment /* @a18n-ignore-file */ to ignore entire file

Extract texts passed to translation calls (will generate zh-CN.json, en.json in ./locales directory):

npx a18n extract src ./locales --locales zh-CN,en

Translate resources under ./locales (e.g. from Chinese to English), after that we should have something like this: (key is added by a18n tool, value is filled by some human translator)

{
  // missing translation, will fallback to original key
  "no-translation": null,

  // static text
  "早上好": "Good morning",

  // dynamic text
  "%s是最好吃的": "pizza is better than %s",
}

Load translation resources and specify language at the start of your application, this must be done BEFORE running any other code

import a18n from 'a18n'
a18n.addLocaleResource('en', require('./en.json'))
a18n.setLocale('en')

// now, a18n() will produce translated result
a18n('早上好') // === "Good morning"

const food = 'A'
a18n`${food}是最好吃的` // === "pizza is better than A"

Documentation

API

a18n(text)

This function can/should be auto-added by a18n wrap command

Translate static text, text should be literal string (instead of variable), example:

a18n('你好') // good
a18n(greeting) // bad, `a18n extract` cannot extract "你好" by analyzing code

a18n`text${variable}`

This function can/should be auto-added by a18n wrap command

Translate dynamic text.

This is an ES6 syntax called Tagged Template Literal

a18n.x`text${variable}`

This function cannot be auto-added, and should be added by user.

Translate dynamic text, returns an array containing translated parts.

This method is useful for displaying mixed content.

const greeting = <div>{a18n.x`Hello ${<strong>Jimmy<strong>}`}</div>
// could evaluate to:
// <div>你好 <strong>Jimmy<strong></div>

a18n.setLocale(locale)

Set locale to use.

This method should be called BEFORE every a18n translation functions are called.

a18n use navigator.language as initial value

a18n.addLocaleResource(locale, resource)

Add resource for specified locale. Resource is usually extracted using a18n extract command.

Example resource:

{
  // missing translation, will fallback to original key
  "no-translation": null,

  // static text
  "早上好": "Good morning",

  // dynamic text
  "%s是最好吃的": "pizza is better than %s"
}

Will merge with existing resource and overwrite values that have same keys.

This method should be called BEFORE every a18n translation functions are called.

(Advanced) a18n.getA18n(namespace)

this method is usually auto added with a18n wrap command, with --namespace option

Get an a18n instance with specified namespace.

Difference namespaces will yield different a18n instances, each with independent locale/resources. Same namespaces will yield same a18n instance, with shared locale/resources.

This API enables:

Sharing a18n instance/resources from different parts of system (even from different copies of a18n code)
NOT sharing a18n instance/resources with other parts of system (even from same piece of a18n code)

Limitation:

Sharing only applies where a18n code are running in the same page and have same reference of globalThis, and cannot share across different browser tabs, web workers, embedded iframes.

See Q & A for more background.

CLI

See: npx a18n --help

Q & A

1. Why is it important to load translation resources and specify a locale before all other code is run?

This can be illustrated with this example:

const s = a18n('apple') // we don't have locale resources for the moment
// so `s` is bound to 'apple', not '苹果' as we intended.

a18n.addLocaleResource('zh-CN', { apple: '苹果' }) // ...too late
a18n.setLocale('zh-CN') // ...too late

console.log(s) // 'apple'

2. When do I need to specify a namespace?

If there are multiple dependencies in the project that further depends on a18n, some bundling tools (webpack) may generate a bundle where they all share a single copy of the a18n code and a single copy of the a18n instance at runtime. Since a18n is a singleton, this may cause unintended locale resources sharing/conflict.

To solve this problem, different dependencies can get its own a18n instances, differentiated by namespace, using getA18n(namespace), and continue to have isolated resources and language configurations. It is also possible to acquire the same a18n instance by specifying same namespaces in order to share language and translation resources.

Usage no npm install needed!