auto-i18n

🌐 Auto I18N

Auto I18N is a package which automagically translate your JSON files, objects, or strings using Google Translate. It's automating your internationalization.

⭐ Usage

Add the dependency from NPM:

npm install auto-i18n

Import the modules you require from the package:

import * from "auto-i18n";

And then configure your Project ID and API key as environment variables (see Configuration).

Translating words

To translate a single phrase:

import { translate } from "auto-i18n";
const hello = await translate("Hello!", "fr"); // Bonjour!

For every function, can also use promises:

translate("Hello!", "nl")
  .then(translation => {
      console.log(translation); // Hallo!
  })
  .catch(error => {
      console.log("Got an error", error);
  });

Translating objects

To translate an entire object:

import { translateObject } from "auto-i18n";
const translateMe = {
    hello: "Hello",
    world: ["world", "earth"]
};
const translated = await translateObject(translateMe, "es");
console.log(translated);
/* { hello: "Hola",
     world: ["mundo", "tierra"] } */

Translating a single-translation file

A single translation file is a JSON file which contains keys for language codes and terms under each key. You can write one for English like this, for example:

File en.json:

{
    "en": {
        "greeting": "Hello!",
        "question": "How are you?"
    }
}

To translate it, use the translateFileSingle function:

import { translateFileSingle } from "auto-i18n";
import path from "path"; // Node.js path helper
const filePath = path.join(__dirname, "en.json");
const translated = await translateFileSingle(filePath, ["fr", "nl", "es"]);
console.log(translated);

This is what translated looks like:

{
    "en": {
        "greeting": "Hello!",
        "question": "How are you?"
    },
    "fr": {
        "greeting": "Bonjour!",
        "question": "Comment vas-tu?"
    },
    "nl": {
        "greeting": "Hallo!",
        "question": "Hoe gaat het met je?"
    },
    "es": {
        "greeting": "Hola!",
        "question": "¿Cómo estás?"
    }
}

You can also write the file directly by supplying the third parameter as true:

await translateFileSingle(filePath, ["fr", "nl", "es"], true);

Translation a regular JSON file

If you have a JSON file which is not a single-translation-file, you can also translate it:

await translateFile(
    "en.json", /* File path */
    "nl", /* Language code (single) */
    false /* Overwrite the file with translation? */
);

Generated translated files

If you have a JSON file (e.g., en.json), you can also generate corresponding language files:

await generate(
    "en.json", /* File path */
    ["nl", "fr", "es"], /* Languages */
);

💡 Notes

Caching

Auto I18N uses local caching powered by Fraud to decrease API usage and therefore billing. A caching directory, .cache/auto-i18n is used, which should be added to your .gitignore. You can overwrite this directory as a parameter in each function.

Configuration

Auto I18N uses the Google Cloud Translation API, for which an API key and Project ID are required. These should be available as environment variables in your .env file. For example:

PROJECT_ID = "google-cloud-project-id"
API_KEY = "google-cloud-api-key"

The library will automatically read them from the .env file, as long as it's in your project root directory.

🛠️ Development

Install dependencies:

yarn

Compile Typescript to ES6 before publishing to NPM:

yarn build

📝 License

MIT