README

Description

Library contains tools to build end-to-end translation process inside CI pipeline.

Install

npm install @targetprocess/translation-tools

yarn add @targetprocess/translation-tools

Prerequisites

Localizable solution has to include the following parts:

Transifex project's resource.
Git repository with localization dictionaries.
Source project which contains strings in localizable format inside its source code. Project uses localization dictionaries to take string's translated value according to the current locale.

Translation process

Scan source project and extract localizable strings.
Send extracted strings to Transifex.
Download translated resources from Transifex and push them to localization dictionaries repository.

Format of localizable strings

tau-extract-gettext is used to extract localizable strings from the source project. Please refer to this library for information about the format of localizable strings.

Transifex configuration

tau-transifex is used to send extracted localizable strings to Transifex and download translated resources form Transifex. Please refer to this library for information about Transifex configuration options.

Example of usage

Add translation script.

scripts/localization/translator.js

const process = require('process');

// Function to perform end-to-end translation of the source project
// See "Translation process" section and function documentation for more details
const translate = require('@targetprocess/translation-tools');

// Path to the source project with localizable strings
const [, , sourcePath] = process.argv;

const transifexConfig = {
    login: process.env.TRANSIFEX_LOGIN,
    password: process.env.TRANSIFEX_PASSWORD,
    projectSlug: 'project-name',
    resourceSlug: 'resource-name',
    stringWillRemove: { tags: ['to-delete'] },
    // optional log level ('error' by default).
    // logLevel: 'debug'
};

// URL to Git repository with localization dictionaries
const dictionariesRepoUrl = process.env.DICTIONARIES_REPO;

translate(sourcePath, transifexConfig, dictionariesRepoUrl)
    .catch(error => {
        console.error(error);
        return process.exit(1);
    });

Add .gitlab-ci localization job definition.
Localization dictionaries repository can be updated during this job. Therefore localization stage should precede libraries installation stage for the source project.

localization:
  stage: localization
  image: targetprocess/docker-node-alpine-build:carbon
  only:
    - master
  script:
    # Add SSH key to access localization dictionaries repo
    - chmod +x scripts/ci/add-gitlab-ssh.sh
    - ./scripts/ci/add-gitlab-ssh.sh
    # Configure Git to push translated resources to localization dictionaries repo
    - git config --global user.email "myproject@targetprocess.com"
    - git config --global user.name "Translation bot"
    # Execute translation script
    - cd scripts/localization
    - yarn add @targetprocess/translation-tools
    - node translator.js path-to-the-source-project

Make sure to upgrade the reference to localization dictionaries repository.

...
- yarn upgrade localization-dictionaries
- yarn install
...

Usage no npm install needed!