translation-markup v0.0.4

translation-markup

A node pre-compiler for reading translation markup files and generating corresponding JSON based language translations.

Install

npm i @shiftcode/translation-markup

Translation Markup - TL

The translation markup intends to drastically reduce the amount of typing needed to translate your app by keeping it simple and improving it's maintenance.

Briefing

A translation file begins with the declaration of all supported languages of your application. A custom numeric code (key) must be assigned to each one of the declared languages. In the sample that comes next, we're saying that american english code is 1, brazilian portuguese is 2 and spanish from spain is 3. Translation values are assigned directly to the language key.

Sample TL markup

LANGUAGES
  1:enUs
  2:ptBr
  3:esEs

MENU
  USER
    LABEL
      1:User
      2:Usuário
      3:Usuario
    DROPDOWN
      EDIT
        1:Edit
        2,3:Editar
      LOGOUT
        1:Logout
        2:Sair
        3:Finalizar la Sesión
  CART
    EMPTY
      1:Empty Cart
      2:Esvaziar Carrinho
      3:Vaciar Carrito
    CHECKOUT
      1:Checkout
      2:Fechar Pedido
      3:Realizar Pedido
    NEWLINE
      1:Test\nText in a new line

Compiling the above will result in the following:

var angTranslations = {
  "enUs": {
    "MENU": {
      "USER": {
        "LABEL": "User",
        "DROPDOWN": {
          "EDIT": "Edit",
          "LOGOUT": "Logout"
        }
      },
      "CART": {
        "EMPTY": "Empty Cart",
        "CHECKOUT": "Checkout"
      },
      "NEWLINE": "Test\nText in a new line"
    }
  },
  "ptBr": {
    "MENU": {
      "USER": {
        "LABEL": "Usuário",
        "DROPDOWN": {
          "EDIT": "Editar",
          "LOGOUT": "Sair"
        }
      },
      "CART": {
        "EMPTY": "Esvaziar Carrinho",
        "CHECKOUT": "Fechar Pedido"
      }
    }
  },
  "esEs": {
    "MENU": {
      "USER": {
        "LABEL": "Usuario",
        "DROPDOWN": {
          "EDIT": "Editar",
          "LOGOUT": "Finalizar la Sesión"
        }
      },
      "CART": {
        "EMPTY": "Vaciar Carrito",
        "CHECKOUT": "Realizar Pedido"
      }
    }
  }
};

Notice how the syntax is greatly simplified as it's no longer needed to rewrite every key for each language and there are no need for quotes or blocks. This way we can focus on what really matters, the translations. Maintenance is also greatly improved, as adding a new key will no longer be a hunt for the right spot of each language. Equal translations are also simpler, as you can assign the same value for multiple language keys (e.g., the user.dropdown.edit key in the above example).

For multiple lines in a key value just use '\n' like in the example above.

API

> parseFile(filePath, indentChar)

Arguments

• filePath: String

  • Path to the .tl file

• indentChar: String

  • Indentation character used in the .tl file (default: tab)
  • Ex: '\t' for tabs, ' ' for single spaces, etc

Return

• Promise that resolves after file was parsed with:
• Object
  • Javascript object where each key is a language and their respective values are the objects with the translations.

Usage

const tl = require('@shiftcode/translation-markup');
const filePath = './translations.tl';
const result = tl.parseFile(filePath); // indent char is tab by default

console.log(result);
// result = {
//   enUs: {
//     USER: {
//       LABEL: 'User',
//       NAME: 'Name'
//     }
//   },
//   ptBr: {
//     USER: {
//       LABEL: 'Usuário',
//       NAME: 'Nome'
//     }
//   }
// }

with translations.tl:

LANGUAGES
  1:enUs
  2:ptBr

USER
  LABEL
    1:User
    2:Usuário
  NAME
    1:Name
    2:Nome

> parseString(markupString, indentChar)

Arguments

• markupString: String

  • String in the same format as the .tl file

• indentChar: String

  • Indentation character used in the .tl file (default: tab)
  • Ex: '\t' for tabs, ' ' for single spaces, etc

Return

• Object
  • Javascript object where each key is a language and their respective values are the objects with the translations.

Usage

const tl = require('@shiftcode/translation-markup');
const fs = require('fs');

const filePath = './translations.tl';
const fileString = fs.readFileSync(filePath).toString();

const result = tl.parseString(fileString); // indent char is tab by default

console.log(result);
// result = {
//   enUs: {
//     USER: {
//       LABEL: 'User',
//       NAME: 'Name'
//     }
//   },
//   ptBr: {
//     USER: {
//       LABEL: 'Usuário',
//       NAME: 'Nome'
//     }
//   }
// }

with translations.tl:

LANGUAGES
  1:enUs
  2:ptBr

USER
  LABEL
    1:User
    2:Usuário
  NAME
    1:Name
    2:Nome

> compile(filePaths , destPath, options)

Arguments

• filePaths: String[]

  • Array with the paths of all .tl files to be parsed

• destPath: String

  • Path where the resulting .js/.json file will be created

• options: Object

  • translationVar: (default: 'angTranslations')
    • Name of the variable used to assign the object resulting from the parsing.
    • Not used when either multipleObjects or asJson is true.
  • multipleObjects: (default: false)
    • If true, each language will be stored in a different variable.
    • e.g., var enUs = {...}; var ptBr = {...}
    • or, with moduleExports = true, module.exports.enUs = {...}; module.exports.ptBr = {...}
  • filePerLang: (default: false)
    • If true, stores each language translation object in a different file.
    • The destination file path must have contain {lang}, which will be replaced by each of the language names.
    • e.g., outputPath = './translationResult_{lang}.js'; with a .tl file with the langages enUs and ptBr will create the files translationResult_enUs.js and translationResult_ptBr.js.
  • moduleExports: (default: false)
    • If true, will output the resulting object in a module.exports instead of a var.
    • e.g., module.exports.angTranslations = {...};
  • asJson: (default: false)
    • If true, will output the resulting object directly as a JSON.
    • e.g., {...} or, if used with moduleExports = true, module.exports = {...}
  • indentation: (default: '\t')
    • Indentation character used in the .tl file
    • Ex: '\t' for tabs, ' ' for single spaces, etc

Return

• Promise that resolves after all files were read, parsed and output file was written

Usage

const tl = require('@shiftcode/translation-markup');

const userPath = './user.tl';
const countriesPath = './countries.tl';

const outputPath = './translationResult.js';

const options = {};
// default options
// {
//   translationVar: 'angTranslations',
//   multipleObjects: false,
//   filePerLang: false,
//   moduleExports: false,
//   asJson: false,
//   indentation: '\t'
// }

tl.compile([userPath, countriesPath], outputPath, options);
// file in the outputPath will be created with the result

Having the following .tl files:

user.tl

LANGUAGES
  1:enUs
  2:ptBr

USER
  LABEL
    1:User
    2:Usuário
  NAME
    1:Name
    2:Nome

countries.tl

LANGUAGES
  1:enUs
  2:ptBr

COUNTRIES
  US
    1:United States of America
    2:Estados Unidos da América
  BR
    1:Brazil
    2:Brasil

Will result in the following translationResult.js file:

var angTranslations = {
  enUs: {
    USER: {
      LABEL: 'User',
      NAME: 'Nome'
    },
    COUNTRIES: {
      US: '',
      BR: ''
    }
  },
  ptBr: {
    USER: {
      LABEL: 'Usuário',
      NAME: 'Nome'
    },
    COUNTRIES: {
      US: '',
      BR: ''
    }
  }
};