translations-util

Command line tools for extracting and importing translations from and to Excel files.

Installation

CLI tool

Installs the package globally so that you can use the command line tool from anywhere.

pip install translations-util

Install as a Python package

Installation with Poetry

To install using Poetry:

poetry add -D translations-util

Which will install the utils as a development dependency in your local python environment.

Usage

This tool allows you to update translations in a TypeScript file based on an Excel file. The Excel file should contain the translations in a specific format.

CLI usage

Command

translation-util {import,export} ...

Import Command

translation-util import <excel_file> <ts_file> <sheet_name>

• <excel_file>: Path to the Excel file containing the translations.
• <ts_file>: Path to the TypeScript file to be updated.
• <sheet_name>: Name of the sheet in the Excel file that contains the translations.

Export Command

translation-util export <ts_file> <excel_file> <sheet_name>

• <ts_file>: Path to the TypeScript file containing translations.
• <excel_file>: Path to the Excel file to save exported translations.
• <sheet_name>: Sheet name to save translations under in the Excel file.

Example

translation-util import path/to/translations.xlsx path/to/translations-french.ts French

This command will update the translations-french.ts file with the French translations from the translations.xlsx file, under the French Excel sheet name.

translation-util export path/to/translations-french.ts path/to/translations.xlsx French

This command will export the translations from the translations-french.ts file to the translations.xlsx file, under the French Excel sheet name. The Excel will follow the format from the Excel File Format section.

Excel File Format

The Excel file should have at least three columns:

1. Key: The key for the translation.
2. English Text: The original English text.
3. Translation: The translated text.

Features

• Placeholder Matching: Ensures that placeholders in the format {variable} are consistent between the English text and the translation.
• Translation Blocks: Detects and processes translation blocks marked by // TODO: vvv Translate below vvv and // TODO: ^^^ Translate above ^^^.

Example

Assuming the Excel workbook has a sheet named French with the following content:

Key	English Text	French text
common.greeting-{name}	Hello, {name}!	Bonjour, {name}!
common.goodbye	Goodbye!	Au revoir!
login.username	Username	Nom d'utilisateur
login.password	Password
error.invalid-translation-of-variable-{name}	Invalid translation of variable {name}	Traduction invalide de variable {nom}

The import-translations command will update the TypeScript file with the following content:

export const translations = {
    ..., // Other translations
    'common.existing-translation': 'Traduction existante',
    'common.greeting-{name}': 'Bonjour, {name}!',
    'common.goodbye': 'Au revoir!',
    'login.username': "Nom d'utilisateur",
    'login.password': '', // TODO Translate
    'error.invalid-translation-of-variable-{name}': '', // TODO Translate
    ... // Other translations
};

Development

To contribute to this project, clone the repository and install the dependencies using Poetry:

git clone <repository-url>
cd translations-util
poetry install

License

This project is licensed under the MIT License - see the LICENSE file for details.