npm package: @phila/auto-translator-cli
Description: A tool to translate and manage localization files.
Latest version: 1.2.0

# @phila/auto-translator-cli

This tool will translate all of the keys in a json object into any other languages that Amazon Translate offers.

It can be found at [https://www.npmjs.com/package/@phila/auto-translator-cli](https://www.npmjs.com/package/@phila/auto-translator-cli).

# Installation

To use `auto-translator-cli`, first install it globally using

    npm i -g @phila/auto-translator-cli

# Setup

Any project that uses it should, by default, have an i18n folder at the location src/i18n:

<img src="https://vue3-app-images.s3.us-east-1.amazonaws.com/auto-translator-cli/i18nFolder.png" alt="i18n-folder" />

This location and folder name can be anything, but the cli questions are set to import and export from src/i18n by default

<img src="https://vue3-app-images.s3.us-east-1.amazonaws.com/auto-translator-cli/importFolder.png" alt="import-folder" />
<img src="https://vue3-app-images.s3.us-east-1.amazonaws.com/auto-translator-cli/exportFolder.png" alt="export-folder" />

The english file you import can be a .js file, and it should export a JSON object:

<img src="https://vue3-app-images.s3.us-east-1.amazonaws.com/auto-translator-cli/exportJs.png" alt="english-file" />

This object MUST

* use "" around all keys and values
* not have any trailing commas after the last entry in a nested object

# Branching

The typical way to use this is to be working in a branch where you have branched off from the `main` branch.  Running from there, you will first be comparing your `en.js` file to the `en.js` file in the `main` branch.  That way it will only bother translating lines in your current branch's `en.js` that have changed since your branched off of `main`.

Note, you do have the chance to set it to compare to any branch, it does not have to be `main`.  The git branch to use for comparison is one of the questions that the CLI will ask.

# Use

To run the auto-translator, go to a project's base folder and in the cmd line run:

    auto-translator

It will ask 6 questions:

<img src="https://vue3-app-images.s3.us-east-1.amazonaws.com/auto-translator-cli/5questions.png" alt="questions" />

The default answers for those questions will be correct for almost any situation, so unless you are using a special case, you can simply hit enter through all 6 questions to accept the default values.

In some cases an english file may be named `en-us.js`, and then the default of `en.js` will have to be overridden.  Or you may want to compare your changes to `en.js` against a branch other than `main`, and will have to enter the branch name.

# Adding New Languages

You can use the LANGUAGES prompt to create translations for languages that don't exist yet in your project. Enter a comma-separated list of language codes (e.g., `pt,ht,ar`) to target specific languages, or leave it as `all` to update all existing language files.

When creating new language files, the tool will:
1. Create the new translation files (e.g., `pt.js`, `ht.js`, `ar.js`)
2. Automatically update your `i18n.js` config file with the necessary imports, language entries, and message mappings

Supported language codes include: `es`, `ch`, `vi`, `ru`, `fr`, `pt` (Portuguese), `ht` (Haitian Creole), `ar` (Arabic), and any other language supported by Amazon Translate.

# Troubleshooting

The input files MUST export a perfect JSON object.  The process will break if it reads in a file in which there is a single extra comma, or a missing quotation mark.