radius-i18n

radius-i18n is a tool designed to simplify internationalization (i18n) by leveraging Google Vertex AI to generate translations and manage localization files. With radius-i18n, you can automate the creation of translation strings and enhance them with detailed notes for precise generation.

---

Installation

To install radius-i18n as a development dependency, run:

• npm:

  npm install radius-i18n --save-dev

• Yarn:

  yarn add radius-i18n --dev

This will add radius-i18n to your devDependencies.

---

Configuration

Create a configuration file named radius.config.json in your project root with the following content:

{
  "locale_base": "en",
  "locales": ["en", "id"],
  "locale_path": "./src/locales",
  "change_delay": 2000,
  "service_resource": "./service-account.json"
}

Explanation of Configuration Options:

• locale_base: The primary locale used as the reference for translations.
• locales: List of locales supported by your project.
• locale_path: Directory where localization files will be generated/stored.
  • Important: Ensure the locale_path has read-write access.
• change_delay: Delay (in milliseconds) before applying file changes after saving. Useful to avoid conflicts during repeated saves.
• service_resource: JSON file containing credentials for Google Vertex AI. Ensure this file is secure and properly configured with access permissions.

---

Setup Localization Files

Inside the locale_path directory, create a folder for the base locale (e.g., en) and add a JSON file for translations. For example, header.json:

{
   "homeNavLabel": "",
   "adminNavLabel": "",
   "profileNavLabel": "",
   "subtitleHeader": "",
   "__future__trx__": ["loginBtn", "registerBtn"],
   "__note__": [
       {
           "key": "subtitleHeader",
           "note": "This key is about a machine, create a simple subtitle.",
           "lang": "en"
       }
   ]
}

Key Format:

• Empty Values: Keys with empty values ("") will have their values automatically generated by the tool.
• Pre-filled Values: Keys with pre-filled values will not be overwritten unless explicitly specified in __future__trx__.
• __future__trx__: A list of keys to be replaced or created in future translations, even if their values are non-empty. Useful for updating translations when context changes.
• __note__: An array of notes describing the purpose or context of a key for more accurate AI generation.
  • key: The translation key the note applies to.
  • note: A description to guide the AI.
  • lang: The language of the note.
  • Nested Notes: Use key.child format for child elements.

---

Important Considerations

1. File Access Permissions

Ensure the locale_path directory has read-write access. This is necessary for the tool to monitor, modify, and create localization files dynamically.

2. Completing Notes Before Saving

When adding or updating __note__ entries:

• Do not save the file until you’ve completed writing your notes.
• Once the file is saved and detected by the watcher, the tool executes translation generation.
• Note: After execution, __note__ and __future__trx__ entries will be automatically removed from the JSON file to keep it clean.

3. Error Handling

If translation generation fails or behaves unexpectedly:

• Check the console for error messages.
• Ensure service_resource is correctly configured and has valid credentials.
• Verify that the file structure and keys follow the correct format.

---

Scripts

Add the following script to your package.json:

"scripts": {
  "radius:w": "radius-translate"
}

Run the script to start the watcher:

npm run radius:w

The tool will monitor changes in your localization files and generate translations dynamically.

---

Usage Guidelines

1. Define Your Keys:

   • Leave values empty for auto-generation.
   • Use __future__trx__ for keys you want to predefine for future translations.

2. Add Notes for AI Context:

   • Add context in __note__ to provide the AI with additional information.
   • Use the lang field to specify the language of the note.
   • Important: Ensure notes are complete before saving the file to avoid incomplete translations.

3. Regenerate Translations:

   • Modify the JSON files or add new keys to see updates handled automatically by the watcher.

---

Example Workflow

1. Add a key welcomeMessage with an empty value in your base locale file (en/header.json).
2. The watcher detects the change and generates a translation for welcomeMessage only if:
   • The value is empty.
   • The key is listed in __future__trx__.
3. If you want to ensure welcomeMessage is updated in future runs, add it to __future__trx__.

---

Happy localizing! 🚀