Added i18n support for the name of flags

[mokizzz]

Description:

Added i18n support for the name of flags, which closes #1043.

Added a test to ensure translation completeness when new countries (flags) are added in the future, preventing missing translations.

The screenshot below shows the changes in some flag names after switching to Simplified Chinese:

and supported non-English search:

The following is a one-time script that extracts country codes and names from src/client/data/countries.json. The extracted key-value pairs can be directly copied into resources/lang/en.json. It is provided here for future use. Save this file as tmp.js in the root directory, and then run node tmp.js.

#!/usr/bin/env node

import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const countriesPath = path.join(__dirname, 'src/client/data/countries.json');
const countries = JSON.parse(fs.readFileSync(countriesPath, 'utf8'));

function countryCodeToTranslationKey(countryCode) {
  return countryCode
    .toLowerCase()
    .replace(/\s+/g, "_") // Convert spaces to underscores
    .replace(/[^a-z0-9\-_]/g, "") // Remove special characters, keep hyphens and underscores
    .replace(/_+/g, "_") // Collapse multiple underscores
    .replace(/^_|_$/g, ""); // Remove leading/trailing underscores
}

console.log('// Generated country translation key-value pairs, copy to en.json "countries" section:');
console.log('');

countries.forEach((country, index) => {
  const normalizedKey = countryCodeToTranslationKey(country.code);
  const isLast = index === countries.length - 1;
  const comma = isLast ? '' : ',';
  
  console.log(`    "${normalizedKey}": "${country.name}"${comma}`);
});

console.log('');
console.log(`// Total ${countries.length} countries`);
console.log('// Script execution completed! Copy the content above to en.json');

Please complete the following:

• I have added screenshots for all UI updates
• I process any text displayed to the user through translateText() and I've added it to the en.json file
• I have added relevant tests to the test directory
• I confirm I have thoroughly tested these changes and take full responsibility for any bugs introduced

Please put your Discord username so you can be contacted if a bug or regression is found:

yumika8269

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/client/FlagInputModal.ts (1)

22-33: Localize UI strings and use @input for live search (IME-friendly).

Two UI strings are still hard-coded: modal title and placeholder. Also, prefer @input over @keyup/@change for smoother typing and IME support.

-      <o-modal title="Flag Selector Modal" alwaysMaximized>
+      <o-modal title=${translateText("flag.modal.title")} alwaysMaximized>
         <input
           class="h-[2rem] border-none border border-gray-300
           rounded-xl shadow-sm text-2xl text-center focus:outline-none
           focus:ring-2 focus:ring-blue-500 focus:border-blue-500 text-black
           dark:border-gray-300/60 dark:bg-gray-700 dark:text-white"
 
           type="text"
-          placeholder="Search..."
-          @change=${this.handleSearch}
-          @keyup=${this.handleSearch}
+          placeholder=${translateText("flag.search.placeholder")}
+          autocomplete="off"
+          enterkeyhint="search"
+          @input=${this.handleSearch}
         />

Additional change outside this hunk: ensure translateText is imported or otherwise in scope in this file (adjust path to your i18n util as needed):

-import { getTranslatedCountryName } from "./Utils";
+import { getTranslatedCountryName, translateText } from "./Utils";

If translateText lives elsewhere, import from the correct module instead.

🧹 Nitpick comments (5)

src/client/FlagInputModal.ts (5)

62-62: Display uses translated country name — nice. Consider avoiding duplicate lookups.

We call getTranslatedCountryName here and again inside includedInSearch. It’s cheap, but we can avoid extra work by letting includedInSearch accept an optional precomputed localized name.

Apply this focused change to the search helper; then you can optionally pass the localized name from the caller:

-  private includedInSearch(country: { name: string; code: string }): boolean {
-    const q = this.search.toLowerCase();
-    const localized = getTranslatedCountryName(country.code, country.name).toLowerCase();
+  private includedInSearch(
+    country: { name: string; code: string },
+    localizedName?: string,
+  ): boolean {
+    const q = this.search.trim().toLowerCase();
+    if (!q) return true;
+    const name = country.name.toLowerCase();
+    const code = country.code.toLowerCase();
+    const localized = (localizedName ?? getTranslatedCountryName(country.code, country.name)).toLowerCase();
     return (
-      country.name.toLowerCase().includes(q) ||
-      country.code.toLowerCase().includes(q) ||
+      name.includes(q) ||
+      code.includes(q) ||
       localized.includes(q)
     );
   }

Optional follow-up in the list rendering (compute once per country and pass into the helper):

-          ${this.isModalOpen ? Countries.filter(
-            (country) => !country.restricted && this.includedInSearch(country),
-          ).map(
-            (country) => html`
+          ${this.isModalOpen ? Countries
+            .map((country) => ({ country, localized: getTranslatedCountryName(country.code, country.name) }))
+            .filter(({ country, localized }) => !country.restricted && this.includedInSearch(country, localized))
+            .map(({ country, localized }) => html`
               ...
-                <span class="country-name">${getTranslatedCountryName(country.code, country.name)}</span>
+                <span class="country-name">${localized}</span>
               </button>
             `)
           : html``}

---

72-78: Search UX: trim input, early-return on empty query, and reuse normalized fields.

Small wins: trim whitespace, avoid repeating toLowerCase() calls, and keep behavior the same (empty query shows all).

Included in the diff above for includedInSearch. No functional change, just cleaner and a bit faster.

---

51-61: Add alt and lazy-loading to flag images (accessibility + perf).

The image is decorative because the country name is shown as text. Use empty alt to prevent double announcement by screen readers and enable lazy loading.

-                <img
+                <img
                   class="country-flag w-full h-auto"
                   src="/flags/${country.code}.svg"
+                  alt=""
+                  aria-hidden="true"
+                  loading="lazy"
+                  decoding="async"
                   @error=${(e: Event) => {
                     const img = e.currentTarget as HTMLImageElement;
                     const fallback = "/flags/xx.svg";
                     if (img.src && !img.src.endsWith(fallback)) {
                       img.src = fallback;
                     }
                   }}
                 />

---

96-103: Clear search when opening the modal (optional).

Nice-to-have: reset this.search on open() so users always see the full list when they reopen the modal.

   public open() {
-    this.isModalOpen = true;
+    this.isModalOpen = true;
+    this.search = "";
     this.modalEl?.open();
   }

---

71-79: Add lightweight tests for search behavior (en + localized).

We added i18n for names and search by localized text. Suggest adding a small client test that verifies:

• English name match works
• Localized name match works (e.g., a known zh‑CN entry)
• Code match works (e.g., “us”, “fr”)

I can draft the test scaffold to cover these cases if helpful.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 7ad5e63 and e5c012d.

📒 Files selected for processing (1)

• src/client/FlagInputModal.ts (3 hunks)

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: andrewNiziolek
PR: openfrontio/OpenFrontIO#1007
File: resources/lang/de.json:115-115
Timestamp: 2025-06-02T14:27:37.609Z
Learning: For OpenFrontIO project: When localization keys are renamed in language JSON files, the maintainers separate technical changes from translation content updates. They wait for community translators to update the actual translation values rather than attempting to translate in the same PR. This allows technical changes to proceed while ensuring accurate translations from native speakers.

Learnt from: TheGiraffe3
PR: openfrontio/OpenFrontIO#884
File: resources/lang/en.json:456-461
Timestamp: 2025-08-16T10:52:08.292Z
Learning: In OpenFrontIO, translation files in resources/lang/*.json (except en.json) should not be updated in regular PRs. Only dedicated translation PRs titled "mls" and made by Aotumori should update non-English locale files. Regular PRs should only update en.json when adding or modifying translation keys.

Learnt from: VariableVince
PR: openfrontio/OpenFrontIO#1655
File: resources/maps/giantworldmap/manifest.json:165-174
Timestamp: 2025-07-31T12:03:08.052Z
Learning: In OpenFrontIO draft PRs, flag names in map manifest files may be placeholders that will be updated to match the actual SVG flag file names when the assets are received. The final naming depends on the actual flag SVG files provided, not code naming conventions.

Learnt from: VariableVince
PR: openfrontio/OpenFrontIO#959
File: resources/maps/GatewayToTheAtlantic.json:124-124
Timestamp: 2025-05-30T18:11:56.014Z
Learning: In OpenFrontIO, flag names in map JSON files can use spaces (like "Amazigh flag") and don't need to follow slug format. Flag assets are stored with matching filenames including spaces (e.g., "Amazigh flag.svg"). Nation names and flag names are not translated/localized in the translation files.

🧬 Code graph analysis (1)

src/client/FlagInputModal.ts (1)

src/client/Utils.ts (1)

• getTranslatedCountryName (149-161)

🔇 Additional comments (1)

src/client/FlagInputModal.ts (1)

4-4: Import looks good; confirm locale-file policy (zh-CN changes).

Good call to centralize country name translation in Utils. One process note: maintainers prefer that only en.json is updated in regular PRs; non‑English locales (e.g., zh‑CN) are handled in dedicated translation PRs (“mls”) by Aotumori. Please confirm and, if needed, move zh‑CN changes out of this PR and keep only the new keys in en.json.

Based on past maintainer guidance stored in learnings. I can help split the changes if you want.

[scottanderson]

@mokizzz please link the related issue using one of the supported keywords in the PR description. Thanks!

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

resources/lang/en.json (1)

664-664: Hyphenated codes retained — correct.

Keeping hyphens (e.g., sh-ac, es-pv, es-ct, gb-eng, sh-hl, gb-sct, sh-ta, gb-wls) matches countries.json and the normalization regex. No renames needed.

Also applies to: 680-680, 713-713, 765-765, 987-987, 1003-1003, 1056-1056, 1086-1086

🧹 Nitpick comments (2)

resources/lang/en.json (1)

632-1104: Add a CI check to catch flag-key drift

We ran the verifier script and confirmed there are no extra or missing keys right now. To keep things in sync as country codes change, let’s integrate this check into CI:

• Create a script (e.g. scripts/check-flag-drift.sh) using the provided Python+bash snippet that compares resources/lang/en.json against src/client/data/countries.json.
• In your CI config (e.g. .github/workflows/ci.yml), add a step named “check-flag-drift” that invokes

  bash scripts/check-flag-drift.sh
  

  and fails the build if any drift is found (exit code ≠ 0).
• Log the output so reviewers can see which keys are out of sync.

This guard will prevent stale keys from accumulating when country lists or codes are updated.

src/client/Utils.ts (1)

167-178: Optional: memoize per language to cut repeated DOM lookups during search.

Small cache keyed by currentLang + normalizedCode avoids re-formatting when users type in the modal. Safe, no behavior change.

@@
-export function getTranslatedCountryName(
+const __flagNameCache = new Map<string, string>();
+export function getTranslatedCountryName(
   countryCode: string,
   countryName: string,
 ): string {
   const normalizedCode = normalizeKeyName(countryCode);
   if (!normalizedCode) {
     return countryName;
   }
-  const translationKey = `flags.${normalizedCode}`;
-  const translatedName = translateText(translationKey);
-  return translatedName === translationKey ? countryName : translatedName;
+  const langSelector = document.querySelector("lang-selector") as LangSelector | null;
+  const lang = langSelector?.currentLang ?? "en";
+  const cacheKey = `${lang}:${normalizedCode}`;
+  const cached = __flagNameCache.get(cacheKey);
+  if (cached) return cached;
+
+  const translationKey = `flags.${normalizedCode}`;
+  const translatedName = translateText(translationKey);
+  const result = translatedName === translationKey ? countryName : translatedName;
+  __flagNameCache.set(cacheKey, result);
+  return result;
 }

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between d06ccf8 and 7e4eb4f.

📒 Files selected for processing (3)

• resources/lang/en.json (1 hunks)
• src/client/Utils.ts (1 hunks)
• tests/client/CountryTranslations.test.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/client/CountryTranslations.test.ts

🧰 Additional context used

🧠 Learnings (13)

📓 Common learnings

Learnt from: andrewNiziolek
PR: openfrontio/OpenFrontIO#1007
File: resources/lang/de.json:115-115
Timestamp: 2025-06-02T14:27:37.609Z
Learning: For OpenFrontIO project: When localization keys are renamed in language JSON files, the maintainers separate technical changes from translation content updates. They wait for community translators to update the actual translation values rather than attempting to translate in the same PR. This allows technical changes to proceed while ensuring accurate translations from native speakers.

Learnt from: VariableVince
PR: openfrontio/OpenFrontIO#959
File: resources/maps/GatewayToTheAtlantic.json:124-124
Timestamp: 2025-05-30T18:11:56.014Z
Learning: In OpenFrontIO, flag names in map JSON files can use spaces (like "Amazigh flag") and don't need to follow slug format. Flag assets are stored with matching filenames including spaces (e.g., "Amazigh flag.svg"). Nation names and flag names are not translated/localized in the translation files.

📚 Learning: 2025-08-27T06:56:34.364Z

Learnt from: mokizzz
PR: openfrontio/OpenFrontIO#1940
File: resources/lang/en.json:632-1104
Timestamp: 2025-08-27T06:56:34.364Z
Learning: In OpenFrontIO, country codes in src/client/data/countries.json can contain hyphens (like "austria-hungary", "es-ct", "gb-eng", etc.). The translation keys in resources/lang/en.json correctly preserve these hyphens to match the source data. The normalization function getTranslatedCountryName() maintains hyphens in country codes through its regex pattern.

Applied to files:

• src/client/Utils.ts
• resources/lang/en.json

📚 Learning: 2025-07-23T12:36:35.354Z

Learnt from: Aotumuri
PR: openfrontio/OpenFrontIO#1534
File: src/client/LangSelector.ts:97-106
Timestamp: 2025-07-23T12:36:35.354Z
Learning: In OpenFrontIO's LangSelector.ts, the getClosestSupportedLang method always joins language code parts with underscores ("_") because all keys in the languageMap use underscore format (e.g., pt_BR, sv_SE, zh_CN). This normalization ensures consistency regardless of whether the input language code uses hyphens or underscores as delimiters.

Applied to files:

• src/client/Utils.ts

📚 Learning: 2025-05-30T18:11:56.014Z

Learnt from: VariableVince
PR: openfrontio/OpenFrontIO#959
File: resources/maps/GatewayToTheAtlantic.json:124-124
Timestamp: 2025-05-30T18:11:56.014Z
Learning: In OpenFrontIO, flag names in map JSON files can use spaces (like "Amazigh flag") and don't need to follow slug format. Flag assets are stored with matching filenames including spaces (e.g., "Amazigh flag.svg"). Nation names and flag names are not translated/localized in the translation files.

Applied to files:

• resources/lang/en.json

📚 Learning: 2025-05-30T16:16:27.118Z

Learnt from: VariableVince
PR: openfrontio/OpenFrontIO#957
File: resources/maps/GatewayToTheAtlantic.json:175-179
Timestamp: 2025-05-30T16:16:27.118Z
Learning: In OpenFrontIO project, flag values in map JSON files (like GatewayToTheAtlantic.json) should match the actual flag file names in the resources directory (e.g., "French foreign legion" corresponds to "French foreign legion.svg"). The naming convention follows the file naming system rather than code naming conventions.

Applied to files:

• resources/lang/en.json

📚 Learning: 2025-06-02T14:27:37.609Z

Learnt from: andrewNiziolek
PR: openfrontio/OpenFrontIO#1007
File: resources/lang/de.json:115-115
Timestamp: 2025-06-02T14:27:37.609Z
Learning: For OpenFrontIO project: When localization keys are renamed in language JSON files, the maintainers separate technical changes from translation content updates. They wait for community translators to update the actual translation values rather than attempting to translate in the same PR. This allows technical changes to proceed while ensuring accurate translations from native speakers.

Applied to files:

• resources/lang/en.json

📚 Learning: 2025-08-16T10:52:08.292Z

Learnt from: TheGiraffe3
PR: openfrontio/OpenFrontIO#884
File: resources/lang/en.json:456-461
Timestamp: 2025-08-16T10:52:08.292Z
Learning: In OpenFrontIO, translation files in resources/lang/*.json (except en.json) should not be updated in regular PRs. Only dedicated translation PRs titled "mls" and made by Aotumori should update non-English locale files. Regular PRs should only update en.json when adding or modifying translation keys.

Applied to files:

• resources/lang/en.json

📚 Learning: 2025-07-12T08:41:35.101Z

Learnt from: Aotumuri
PR: openfrontio/OpenFrontIO#1357
File: resources/lang/de.json:523-540
Timestamp: 2025-07-12T08:41:35.101Z
Learning: In OpenFrontIO project localization files, always check the en.json source file before flagging potential spelling errors in other language files, as some keys may intentionally use non-standard spellings that need to be consistent across all translations.

Applied to files:

• resources/lang/en.json

📚 Learning: 2025-08-19T11:00:55.422Z

Learnt from: TheGiraffe3
PR: openfrontio/OpenFrontIO#1864
File: resources/maps/arabianpeninsula/manifest.json:13-170
Timestamp: 2025-08-19T11:00:55.422Z
Learning: In OpenFrontIO, nation names in map manifests are displayed directly in the UI without translation. They do not need to be added to resources/lang/en.json or processed through translateText(). This is the established pattern across all existing maps including Europe, World, Asia, Africa, and others.

Applied to files:

• resources/lang/en.json

📚 Learning: 2025-05-30T03:53:52.231Z

Learnt from: scottanderson
PR: openfrontio/OpenFrontIO#949
File: resources/lang/en.json:8-10
Timestamp: 2025-05-30T03:53:52.231Z
Learning: For the OpenFrontIO project, do not suggest updating translation files in resources/lang/*.json except for en.json. The project has a dedicated translation team that handles all other locale files.

Applied to files:

• resources/lang/en.json

📚 Learning: 2025-07-31T12:03:08.052Z

Learnt from: VariableVince
PR: openfrontio/OpenFrontIO#1655
File: resources/maps/giantworldmap/manifest.json:165-174
Timestamp: 2025-07-31T12:03:08.052Z
Learning: In OpenFrontIO draft PRs, flag names in map manifest files may be placeholders that will be updated to match the actual SVG flag file names when the assets are received. The final naming depends on the actual flag SVG files provided, not code naming conventions.

Applied to files:

• resources/lang/en.json

📚 Learning: 2025-08-10T14:37:35.777Z

Learnt from: TheGiraffe3
PR: openfrontio/OpenFrontIO#1770
File: resources/maps/world/manifest.json:279-355
Timestamp: 2025-08-10T14:37:35.777Z
Learning: The OpenFrontIO World Map includes both real-world nations and fictional/creative entities like "Polar Bears" as playable nations. These special nations may use non-two-letter flag codes (e.g., "polar_bears" instead of a two-letter code), and this is intentional design. The corresponding flag assets are stored in resources/flags/ with matching filenames.

Applied to files:

• resources/lang/en.json

📚 Learning: 2025-05-30T18:11:56.014Z

Learnt from: VariableVince
PR: openfrontio/OpenFrontIO#959
File: resources/maps/GatewayToTheAtlantic.json:124-124
Timestamp: 2025-05-30T18:11:56.014Z
Learning: OpenFrontIO flag naming uses mixed conventions: short country codes (like "cu", "ar"), space-separated names (like "Amazigh flag", "Aztec Empire", "French foreign legion"), underscores (like "santa_claus"), and hyphens (like "gb-eng"). Flag asset filenames match these conventions exactly, including spaces. No translation system exists for flag names or nation names.

Applied to files:

• resources/lang/en.json

🔇 Additional comments (3)

resources/lang/en.json (1)

632-1104: Adding flags. block is correct and aligns with runtime lookups.*

Using a top-level "flags" object (flattened at load to flags.KEY) matches getTranslatedCountryName() and keeps locales clean. Hyphenated keys are preserved as needed.

src/client/Utils.ts (2)

149-165: normalizeKeyName: solid, locale-safe normalization.

NFKD + accent strip + hyphen preservation matches data and tests. Good reuse across code and tests.

---

167-178: flags. prefix and fallback behavior look correct.*

Returns original name when key missing or normalization empties out. Matches en.json structure.

[mokizzz]

Hi @scottanderson , thanks for your review! Above commits should solved your problems.

[Aotumuri]

@scottanderson
Sorry, but if we put all the flag files into Crowdin, there’s a high chance we’ll hit the character limit. Since flags are not expected to change very often, how about saving them outside of en.json in a separate file?
For example, we could store them under something like lang/flag/.... or lang/{lang_code}/main.json - flag.jsom

[Aotumuri]

#1940 (comment)

I think ScottAnderson will propose a better solution, and I’d like you to follow his approach. As it is, I don’t think this can be added directly into Crowdin.

The merge-base changed after approval.

[github-actions]

This pull request is stale because it has been open for fourteen days with no activity. If you want to keep this pull request open, add a comment or update the branch.