T9N CLI

A tiny Node.js based CLI that provides some tools to improve all things around t9n (translation) and i18n (internationalization).

What is this for?

This cli is designed to support developers as well as translators and make their life easier. It...

• 📝 Makes it easy to create a list of type safe translation keys.
• 🪄 Makes it transform these translation keys into something translation agencies can work with (xlsx 🤩).
• 🚨 Shows developers and other stakeholders if translations are missing.
• 🛬 Allows seamless imports of new translations provided by a translation agency.

The Workflow

Everything here is built around the following workflow. Sure, use it however you like, but this was in our mind when we created it.

1. Install this package.
2. Put all translation keys in a file called meta.json and run t9n typedefs <filename> whenever it changes to create a typescript declaration file. Use this declaration file with your translation library to use your translation keys safe. (💡 Using Svelte? Use our Svelte Wrapper to make life even easier.)
3. If it is time to get some actual translations, run t9n export <folderpath> to create a xlsx-sheet with all translation keys. Send this to your translation agency.
4. Once the translation is done, import the translated xlsx with t9n import <filename> to create json files for every defined language. Like en.json, de.json,... .
5. Repeat.

Installation

# using npm
npm install @gira-de/t9n-cli -D

# or using yarn
yarn add @gira-de/t9n-cli -D

You should also be able to use the command line tool via npx:

npx t9n

Usage

Now you need to create some files and put everything together. Here is an example (final) folder structure:

.
└── app/
    ├── src/
    │   └── t9n.ts
    └── locale/
        ├── meta.json
        ├── en.json (<-- updated by t9n cli)
        └── types.ts (<-- generated by t9n cli)

1. Create a file called ./locale/meta.json. This json describes the structure of the actual language files. Every possible translation key as well as a initial translation needs to be described here.

{
  "pageOne": {
    "headline": "This is a fancy headline written by a developer. Don't trust this! 🦹‍♀️🦹‍♂️"
  }
}

2. Create a file called ./locale/.json (for example de.json). This is the actual language file.

{
  "pageOne": {
    "headline": "Das ist die Überschrift von einem echten Übersetzer. Echt. 👩‍🏫👨‍🏫"
  }
}

3. Call the CLI to generate a type definition based on the language files. This command will generate a Typescript declaration file:

npx t9n typedefs ./meta.json -o locale-types.ts

4. Use the generated type definition in your code:

import type { TranslationArgs } from '../locale/types';

Commands

typedefs

This command will generate a Typescript declaration file (*.ts) based on the provided json file.

t9n typedefs <filename>

Flags

-o, --output <filename>     Filename/-path for the declaration file

export

This command creates a xlsx translation file based on a meta.json within a given folder. If there are additional languages files (for example de.json, en.json) within this folder, the command will put this into the resulting xlsx too.

This command currently needs some config:

// t9n.config.json
{
  "version": "0.0.1",
  "worksheetName": "Translation",
  "languages": ["meta", "de"]
};

t9n export <folderpath>

Flags

-o, --output <folderpath> Folderpath for the resulting xlsx

import

Import a translation.xlsx and create .json file out of it (like de.json, en.json,...).

t9n import <excel-input> [--output <folderpath>]

Flags

-o, --output <folderpath> Folderpath for the resulting <language>.json.

check

This command checks all .json compared to a meta.json reference within a given folder. The result will be printed to stdout.

t9n check <input>

Prints a table like this to stdout:

| (index) | __filename | translationKeys | missingTranslationKeys | coverage | missingParams | | ------- | ------------ | --------------- | ---------------------- | -------- | -------------- | | 0 | 'de' | 3 | 1 | 0.67 | [] | | 1 | 'en' | 3 | 2 | 0.33 | ['missingKey'] |