A workflow utility to ease localization in JS(X) apps by automizing the following steps:
narp push
- Extraction of strings from source code (react-gettext-parser)
- Merging upstream and local translations in order to support translations in branches (pot-merge)
- Uploading POT resources to the translation service you use (Transifex or POEditor)
narp pull
- Download PO translations from the translation service
- Converting PO to JSON (gettext-parser)
- Writing the JSON translations to where you want it
The JSON translations are formatted for node-gettext.
Table of Contents
To use it easily, install narp globally with:
npm install -g narpTo use it in an automatization pipeline in your project, install it as a dev dependency:
npm install --save-dev narp# get help
narp -h# extract merge pots upload pot
narp push [<credentials>] [--fresh]# download po's convert to json write to file
narp pull [<credentials>]# extract messages to stdout (no password required)
narp extract [./path/to/comps]Optionally put a path as arg 2 to just extract from the folder. Protip, pipe to file if you want to use it.
import { push, pull } from 'narp';
const configs = {
/* all the configs */
};
push(configs).then(/* ... */).catch(/* ... */);
pull(configs).then(/* ... */).catch(/* ... */);This is the shape of narp's configuration. It can be provided as an object to the pull() and push() functions, or defined as a JSON object in .narprc.
{
// The vendor object differs depending on the vendor
"vendor": {
// The name of the translation service you use.
// Must be "transifex" or "poeditor"
"name": "pick one"
// Credentials used to make authorized HTTP requests.
// See the section below on how to provide passwords
// and tokens.
"credentials": {
// POEditor/Transifex token
"token": "do not store this in a file"
},
// The vendor.options object contain project specific
// options, some of which differ depending on the vendor
"options": {
// Transifex only: The organization slug
"organization": "organization-slug",
// Project ID.
"project": "project-id",
// The source language code. This corresponds to whatever
// the vendor is naming it as.
"sourceLanguage": "en",
// Transifex only: The slug of the resource
"resource": null,
}
},
// Configs that are passed to react-gettext-parser
"extract": {
// A glob string (npmjs.com/glob) that matches all source files
// that may contain translatable strings.
"source": null,
// The rest of the `extract` configs are passed directly to
// react-gettext-parser, see the react-gettext-parser readme.
"componentPropsMap": { /* react-gettext-parser defaults */ },
"funcArgumentsMap": { /* react-gettext-parser defaults */ },
"trim": false,
"trimLines": false,
"trimNewlines": false,
},
// Where to put all the translations
"output": "messages.json",
// Whether the extracted strings should be uploaded without
// being merged with the current upstream source strings,
// thus replacing it
"fresh": false,
// If true, will output debug information to the console
"verbose": false
}You will have to provide different credentials depending on the translation service you use. Transifex requires a username and password, whilst POEditor requires an API token.
There are three ways of providing an API token:
a. Via the --token argument
b. Via the NARP_VENDOR_TOKEN environment variable
c. Via the vendor.credentials.token config passed to the API functions
Never store secret tokens in your code!
There are three ways of providing an API token:
a. Via the --token argument
b. Via the NARP_VENDOR_TOKEN environment variable
c. Via the vendor.credentials.token config passed to the API functions
Never store secret tokens in your code!
.narprc is narp's configuration file. Any configurations you put there will be parsed and applied whenever you use narp.
v3 introduced vendors, which replaces the hard-coded Transifex support with a modularised vendor support, adding POEditor into the mix. To transition your Transifex configuration, you change .narprc from
{
"transifex": {
"username": "yourusername",
"project": "yourproject",
"resource": "yourresource",
"sourceLang": "xx"
},
// More configs...
}to
{
"vendor": {
"name": "transifex",
"credentials": {
"username": "yourusername"
},
"options": {
"project": "yourproject",
"resource": "yourresource",
"sourceLanguage": "xx" // Note that this key is different
}
},
// More configs...
}Updated to use the new Transifex API. Change .narprc from
{
"vendor": {
"name": "transifex",
"credentials": {
"username": "yourusername"
},
"options": {
"project": "yourproject",
"resource": "yourresource",
"sourceLanguage": "xx" // Note that this key is different
}
},
// More configs...
}to
{
"vendor": {
"name": "transifex",
"options": {
"organization": "yourorganization",
"project": "yourproject",
"resource": "yourresource",
"sourceLanguage": "xx" // Note that this key is different
}
},
// More configs...
}# Create a build from source
npm run build
# Build continuously as you save files
npm run build -- --watchcd path/to/narp && npm linkFollow semver when bumping the version number, commit it and run
npm publish