Skip to content
🌐 Automatically translate your JSON I18N files
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests
.gitignore
.travis.yml
LICENSE
README.md
index.ts
languages.ts
package.json
tsconfig.json
yarn.lock

README.md

🌐 Auto I18N

Travis CI Coverage Status GitHub Vulnerabilities NPM type definitions NPM

NPM

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

You can’t perform that action at this time.