This guide explains how to improve existing translations or add support for a new language.

• All translation files are located in the locales/ directory at the root of the project.
• Each language has its own file, named using its language code (e.g., en.json for English, ja.json for Japanese).
• The files use the standard JSON (JavaScript Object Notation) format, specifically a simple object containing "key": "value" pairs.
  • The "key" (e.g., "undoButtonLabel") is a unique identifier used internally by the template code. Please do not change these keys.
  • The "value" (e.g., "Undo") is the actual text string that will be displayed in the template's UI for that language. This is the part you will translate.

Example (en.json snippet):

{
  "undoButtonLabel": "Undo",
  "undoTooltip": "Revert the last reviewed card",
  "shortcutLabel": "Shortcut",
  "flagButtonLabel": "Flag",
  "flagTooltipBase": "Set card flag",
  "flagRed": "Red",
  "flagOrange": "Orange",
  "flagGreen": "Green",
  "flagBlue": "Blue",
  "flagPink": "Pink",
  "flagTurquoise": "Turquoise",
  "flagPurple": "Purple",
  "flagNone": "No Flag",
  // ... more keys
}

To ensure consistency, we use the standard two-letter ISO 639-1 language codes for naming the translation files.

• Examples: en (English), ja (Japanese), fr (French), es (Spanish), de (German), zh (Chinese - often followed by script/region like zh-CN, zh-TW, but start with zh.json if unsure).
• Please use the correct two-letter code when adding a new language file (e.g., fr.json, not fra.json).

Sometimes you might see text in the template UI and want to know which "key" in the .json file corresponds to it. We've added a helper attribute to make this easier:

1. Use the Template in Anki: Open Anki and view a card using this template.
2. Open the WebView Inspector: During review, right-click on the card content and select "Inspect" (or similar - the exact wording might vary slightly). This opens the developer tools focused on the card's HTML.
3. Select the Element: Use the element selector tool (usually looks like a mouse pointer icon in the top-left of the inspector) and click directly on the text element in the card UI that you want to identify.
4. Find the Attribute: Look at the highlighted HTML code in the inspector panel. The element containing the text (often a <span>) should have an attribute like data-i18n-key="someKeyName".

   <!-- Example in Inspector -->
   <span id="flag" data-i18n-key="flagButtonLabel">Flag</span>

5. Identify the Key: The value of the data-i18n-key attribute (flagButtonLabel in the example) is the exact key you need to look for in the .json translation file.

1. Navigate: Go to the locales/ directory.
2. Select File: Open the .json file for the language you want to improve (e.g., ja.json).
3. Find Key: Locate the key corresponding to the text you want to change (use the "Finding the Right Translation Key" method above if needed).
4. Edit Value: Modify the value (the string to the right of the colon) with your improved translation. Ensure the quotes " remain around the string value.
5. Save: Save the changes to the file.
6. Submit: Submit your changes via a Pull Request (see below).

1. Copy Template: In the locales/ directory, make a copy of the en.json file (as it contains all the necessary keys).
2. Rename File: Rename your copied file using the correct two-letter ISO 639-1 code for the language you are adding (e.g., fr.json for French).
3. Translate Values: Open your new xx.json file and translate all the values (the strings on the right side of the colons) into the target language. Remember to leave the keys on the left unchanged.
4. Update Build Script:
   • Open the build.js file at the root of the project.
   • Find the config object near the top.
   • Locate the languages array within the config object.
   • Add the two-letter code for your new language to this array.

     const config = {
       // ... other settings ...
       languages: ['en', 'ja', 'fr'], // <-- Add your new language code 'fr' here
       // ... other settings ...
     };

5. Save: Save the changes to both your new xx.json file and the build.js file.
6. Test (Optional but Recommended): If you have Node.js set up, you can run npm install and then npm run build:templates to ensure the build process works correctly with your new language file. Check the output in build/your-lang-code/.
7. Submit: Submit your new xx.json file and the modification to build.js via a Pull Request (see below). Please mention which language you added in your Pull Request description.

We use the standard GitHub Pull Request workflow:

1. Fork the tyuichis/modern-anki-card-template repository to your own GitHub account.
2. Create a new branch in your fork for your changes (e.g., translate-french or fix-ja-tooltip).
3. Commit your changes to this branch with clear commit messages.
4. Push the branch to your fork on GitHub.
5. Go to the main tyuichis/modern-anki-card-template repository and open a Pull Request comparing your new branch to the main branch of the original repository.
6. Provide a clear description of the changes you made (e.g., "Added French translation" or "Improved Japanese tooltip for Undo button").

If you're new to Pull Requests, GitHub has excellent documentation: "Creating a pull request".

Thank you again for your help!