@datareporter.eu/locint

Localization Server Build Library

For usage in build processes

General usage

Translation of files

const loc = require("src/locint");

// set api key for project
loc.configure({apiKey: "<api key for project>"})

// initialize and load i18n files from server
await loc.initializeWithLanguages({
  isos: ["de", "en"],
  languageFilepath: "./test/_temp",
  invalidFilepath: "./test/_temp/incomplete.json",
  forceLoadFromServer: false,
  format: "json",
  filter: {
    keyFilter : null,
    noSubNodes: false,
    contentType: null,
    editorType : null
  }
});


// now translate all the files you need

// Variant 1: translate content (in memory) ------------------
let translatedContent = loc.translateContent("This is a [[Test]]", "en", "first readme call");

// Variant 2: translate file  ------------------
loc.translateFile(
    "./test/resource/translate_01.html",
    "./test/_temp/translate_en.html",
    "en"
    );

// Variant 3: translate directory with one call (even recursively)--------------
let options = {
  sourceDirectory: "./test/resource",  // path of the files with translation tokens
  recursive: false, // true: recursive search subdirectories
  extensions: ["html", "js"], // allowed file extensions
  destinationDirectory: "./test/_temp", // destination directory where files will be saved
  languages: [ // list of languages to translate to
    {
      iso: "de", // language iso
      appendIsoToFile: false  // true: append iso to filename ( e.g. xxx_de.json)
    },
    {
      iso: "en",
      appendIsoToFile: true
    }
  ]
};
loc.translateDirectory(options);



// after translation save invalid localization status (missing keys, unused keys)
await loc.saveInvalidStatus();

// optional: create missing keys for DE language in locale server
await loc.uploadSavedInvalidStatus("de");

Export files (like markdown) into directory

const loc = require("src/locint");

loc.configure({apiKey: "<api key for project>"})

let result = loc.exportMarkdownFiles({
      destinationPath: "./test/_temp", // destination path where files will be exported to
      isos: ["de", "en"], // iso codes to export
      appendHeader: true, // append language - agnostic header
      appendIsoToFiles: true, // append iso code to filename
      parentNode: null, // parent node key to export from
      extension: ".md" // extension of the generated files
    },
    {
      keyFilter : null, // keyword filter
      noSubNodes: false, // dont add subnodes
      contentType: null, // content type filter (file, !file, gui, ...)
      editorType : null // editor type filter (markdown, line, !text)
    }
);

/*
  result is a list of all exported files like:
    [
      "./test/_temp/gruppentest_01_de.md",
      "./test/_temp/gruppentest_01_en.md"
    ]
 */

Sync a folder to S3

Syncs a folder to S3. Only uploads changed files.

const loc = require("src/locint");

let c = loc.connectToS3("<user key>","<secret>", "test.datareporter.eu");
// c.deltaSync = false; to force upload all files 

let entries = await loc.syncFolderToS3(c, "/Users/mike/testfolder", "s3test");

Formats / Syntax

Translation syntax in templates

Used for downloading localization keys and replacing i18n syntax:

...
[[Abbrechen]] <!-- Token to replace - key is equal to "abbrechen" -->
...
[[!key:Das ist ein Key]] <!-- for longer texts: key is equal to "key" -->
...

Translation key file format

Localization file is a JSON file like:

{
  "list": [
    {
      "key": "Test",
      "description": "",
      "translation": "Übersetzung",
      "contentType": "auto",
      "editorType": "markdown",
      "contentHeader": null
    },
    ...
  ],
  "keys": {
    "key" : {...},
    ...
  }
}

Manual creation and upload of missing/unused keys

let invalids = loc.addInvalidKey();
loc.addInvalidKey(invalids, true, "de", "test-01", "Content-01"); // add missing key
loc.addInvalidKey(invalids, false, "de", "test-02", "Content-02"); // add unused key
// ...

loc.uploadInvalidStatusJson("de", invalids); // upload to server

REST request to translation server

Request to the https://locale.datareporter.eu server is like:

POST /rest/dev/locale-export/format-json HTTP/1.1
apiKey: <api key for project>
Content-Type: application/json; charset=utf-8
Host: locale.datareporter.eu
Connection: close
User-Agent: RapidAPI/4.0.0 (Macintosh; OS X/13.1.0) GCDHTTPRequest
Content-Length: 36

{"languageIso":"de","parentNode":"", mode: "keys,list"}