narp

A workflow utility to ease localization in JS(X) apps by automizing the following steps:

narp push

1. Extraction of strings from source code (react-gettext-parser)
2. Merging upstream and local translations in order to support translations in branches (pot-merge)
3. Uploading POT resources to the translation service you use (Transifex or POEditor)

narp pull

1. Download PO translations from the translation service
2. Converting PO to JSON (gettext-parser)
3. Writing the JSON translations to where you want it

The JSON translations are formatted for node-gettext.

Table of Contents

• Installation
• Usage
  • Using the CLI
  • Using the API
• Configuration
  • Options
  • How to provide credentials
    • Authorizing to Transifex
    • Authorizing to POEditor
  • .narprc
• Migrations
  • Migrating from v2 to v3
• Development
  • Creating builds
  • Making it globally available while testing
  • Releases

Installation

To use it easily, install narp globally with:

npm install -g narp

To use it in an automatization pipeline in your project, install it as a dev dependency:

npm install --save-dev narp

Usage

Using the CLI

# 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.

Using the API

import { push, pull } from 'narp';

const configs = {
  /* all the configs */
};

push(configs).then(/* ... */).catch(/* ... */);

pull(configs).then(/* ... */).catch(/* ... */);

Configuration

Options

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
}

How to provide credentials

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.

Authorizing to Transifex

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!

Authorizing to POEditor

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

.narprc is narp's configuration file. Any configurations you put there will be parsed and applied whenever you use narp.

Migrations

Migrating from v2 to v3

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...
}

Migrating from v3 to v5

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...
}

Development

Creating builds

# Create a build from source
npm run build

# Build continuously as you save files
npm run build -- --watch

Making it globally available while testing

cd path/to/narp && npm link

Releases

Follow semver when bumping the version number, commit it and run

npm publish