npm package: @gira-de/t9n-cli
Description: > A tiny Node.js based CLI that provides some tools to improve all things around t9n (translation) and i18n (internationalization).
Author: GIRA
Latest version: 1.2.0

# 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](/packages/svelte/README.md) 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

```shell
# 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:

```shell
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.

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

2. Create a file called _./locale/<language-key>.json_ (for example de.json). This is the actual language file.

```json
{
  "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:

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

4. Use the generated type definition in your code:

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

## Commands

### typedefs

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

```shell
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:

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

```shell
t9n export <folderpath>
```

**Flags**

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

### import

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

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

**Flags**

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

### check

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

```shell
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'] |