🚀 i18n Sync Tool: Effortless Localization for Your Project

Are you tired of manually managing translation keys and struggling with outdated locale files? The locales.js script is your all-in-one solution for streamlined internationalization (i18n) within your project. This powerful tool automates the entire localization workflow, from scanning your codebase for translation keys to providing an intuitive web interface that integrates seamlessly with AI translation services.

Why You Need This Tool:

• Save Time & Effort: Drastically reduce the manual work involved in managing translations.
• Boost Accuracy: Ensure all your translation keys are accounted for and type-safe.
• Stay Organized: Automatically clean up unused keys, keeping your locale files lean and efficient.
• Leverage AI Power: Generate AI-ready prompts and effortlessly import translations from chatbots, minimizing human translation effort.
• Developer-Friendly: A simple command-line interface combined with a powerful web UI makes localization a breeze for your entire team.

Table of Contents

• 🚀 i18n Sync Tool: Effortless Localization for Your Project
  • Table of Contents
  • ✨ Features
  • Prerequisites
  • File Structure
  • Configuration
  • How to Run the Tool
  • Using the Web Interface
    • Step 1: Generate AI Prompt & Data
    • Step 2: Import Translated Data
    • Step 3: Review and Save
  • Troubleshooting

✨ Features

The locales.js script provides a robust set of features designed to simplify your i18n workflow:

• Intelligent Key Scanning: Automatically scans your project's source code (.js, .jsx, .ts, .tsx files) to identify every t() call. This ensures that no translation key is missed, providing a definitive list of all keys in use.
• Type-Safe Translation Keys: Generates a types.ts file based on the scanned keys. This crucial step provides strong type checking and autocompletion for your translation keys in TypeScript, significantly reducing typos and improving developer productivity.
• Automated Cleanup: Keeps your translation files pristine by automatically removing any keys from your locale JSON files that are no longer referenced in your codebase. Say goodbye to bloated and outdated translation files!
• Interactive Web UI with AI Integration: Launches a local web server with a user-friendly interface that transforms the translation process:
  • Visual Overview: Clearly displays all missing translations across your configured locales.
  • AI-Ready Data Export: Generates a CSV of all missing translations, perfectly formatted for use with any AI translation service (e.g., ChatGPT, Gemini, Claude).
  • One-Click AI Prompt Generation: Creates a pre-formatted, comprehensive prompt for your AI chat model, including all necessary context and data, so you can get accurate translations with minimal effort.
  • Effortless Import: Easily paste the AI-generated CSV translations back into the UI to auto-fill the corresponding fields.
  • Direct Saving: Save all updated translations directly to your locale JSON files with a single click.

Prerequisites

Before running this tool, ensure you have the following installed:

• Node.js: Version 14 or higher.
• npm or Yarn: A package manager for Node.js.

You will also need to install the project dependencies. Navigate to the my-app directory and run:

npm install
# or
yarn install

File Structure

The script interacts with the following key directories and files within your project:

• my-app/scripts/locales.js: The script itself.
• my-app/src/lib/i18n/: The base directory for internationalization files.
  • my-app/src/lib/i18n/locales/: Contains your locale JSON files (e.g., en.json, de.json, es.json, fr.json).
  • my-app/src/lib/i18n/types.ts: The TypeScript declaration file generated by the script, defining the structure of your translation keys.
• my-app/src/: The root directory of your application's source code, which the script scans for t() calls.

Configuration

The script's behavior is controlled by constants defined at the top of locales.js:

• PORT: The port on which the web server will run (default: 3333).
• locales: An array of supported locale codes (e.g., ['en', 'de', 'es', 'fr']). Ensure this matches the locale JSON files you have.
• IGNORE_PATTERNS: An array of glob patterns for directories and files that should be excluded from the translation key scan (e.g., node_modules, build directories, TypeScript declaration files, and the i18n directory itself).

You can modify these values directly in the locales.js file if needed.

How to Run the Tool

To run the i18n Sync Tool, navigate to the my-app directory in your terminal and execute the script using Node.js:

node scripts/locales.js

Upon execution, the script will perform the following steps:

1. Scan for Keys: It will scan your src directory for all t() calls and collect unique translation keys.
2. Generate Types: It will generate or update src/lib/i18n/types.ts with the latest translation key structure.
3. Clean Up Locales: It will remove any unused keys from your src/lib/i18n/locales/*.json files.
4. Launch Web UI: It will start a web server, typically on http://localhost:3333. You will see a message in your terminal indicating the URL to open.

Keep the terminal window open as long as you are using the web interface. To stop the server, press CTRL+C in the terminal.

Using the Web Interface

Once the web server is running, open your browser and navigate to http://localhost:3333 (or the port specified in your configuration). The interface will display a table of all translation keys that are defined in types.ts but are missing translations in one or more of your locale JSON files.

The workflow for adding missing translations is divided into three steps:

Step 1: Generate AI Prompt & Data

This section helps you prepare data for AI translation services.

1. Copy Full Prompt for AI: Click this button to copy a pre-formatted prompt to your clipboard. This prompt includes:

   • Instructions for an expert translator AI.
   • A CSV table of all missing translation keys, including existing translations for context.

2. Paste into AI Chat Model: Paste the copied content directly into your preferred AI chat model (e.g., ChatGPT, Gemini, Claude). The AI will then generate the translations in CSV format.

Step 2: Import Translated Data

After receiving the translated CSV data from your AI model:

1. Paste Translated CSV: Copy the entire CSV block provided by the AI (including the header row) and paste it into the large text area labeled "Paste your translated CSV data here...".
2. Auto-fill Table: Click the "Auto-fill Table from Pasted Data" button. The script will parse the CSV data and automatically populate the corresponding input fields in the table below. A confirmation alert will show how many translations were filled.

Step 3: Review and Save

This is the final step where you review and commit your translations.

1. Review Translations: Carefully review the auto-filled translations in the table. Make any manual corrections or adjustments as needed. Fields that already had translations will be marked as "existing" and are read-only in the UI, while missing fields will be highlighted as "missing" and are editable.
2. Save All Translations: Once you are satisfied with all the translations, click the "Save All Translations" button. The script will update your locale JSON files (en.json, de.json, etc.) with the new translations.

After saving, you will see a success message, and the page will automatically refresh, showing that all locale files are up-to-date (if all keys have been translated).

Troubleshooting

• Server not starting: Check if the PORT (default 3333) is already in use by another application. You can change the PORT constant in locales.js.
• "Could not read file" warnings: Ensure that the workspaceDir and i18nDir configurations are correct and that the script has read permissions for the specified directories and files.
• Keys not being scanned: Verify that your t() calls match the i18nRegex pattern in scanForKeys() and that the files are not excluded by IGNORE_PATTERNS.
• Translations not saving: Check the terminal for any error messages when you click the "Save" button. Ensure the locale JSON files have write permissions.
• AI prompt issues: If the AI prompt is not generating correctly, ensure the missingKeysData and locales variables are correctly populated in the client-side script.