From dc6dd6a6bfb6a4350575f7545d09f98dfd5d39af Mon Sep 17 00:00:00 2001
From: Richard Macarthy <richardmacarthy@hotmail.com>
Date: Sun, 5 Feb 2023 05:44:10 +0000
Subject: [PATCH] Add instructions for adding and editing translations using
 i18n (#1120)

update markdown

Remove ignore_keys
---
 .../find-missing-locales.py                   | 49 +++++++++++++++++++
 website/docs/add_edit_translations.md         | 38 ++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 scripts/frontend-development/find-missing-locales.py
 create mode 100644 website/docs/add_edit_translations.md

diff --git a/scripts/frontend-development/find-missing-locales.py b/scripts/frontend-development/find-missing-locales.py
new file mode 100644
index 00000000..6be52e58
--- /dev/null
+++ b/scripts/frontend-development/find-missing-locales.py
@@ -0,0 +1,49 @@
+from glob import glob
+from json import load
+from os import path
+
+ALL_PATH = "../../website/public/locales/**/*.json"
+DIR = path.dirname(__file__)
+EN_PATH = "../../website/public/locales/en/*.json"
+
+
+def get_not_translated(en_json, translation_json, parent_key=None):
+    not_translated = []
+    for key in en_json.keys():
+        if key in translation_json and translation_json[key] == en_json[key]:
+            not_translated.append(("{0}.{1}".format(parent_key, key) if parent_key else key))
+        elif isinstance(en_json[key], dict):
+            not_translated.extend(get_not_translated(en_json[key], translation_json[key], key))
+    return not_translated
+
+
+def get_missing(en_json, translation_json):
+    return [key for key in en_json.keys() if key not in translation_json]
+
+
+def print_result(missing, not_translated, file):
+    if len(missing):
+        print("[{0}] - missing: {1} {2}".format(path.basename(path.dirname(file)), path.basename(file), missing))
+    if len(not_translated):
+        print(
+            "[{0}] - potentially untranslated: {1} {2}".format(
+                path.basename(path.dirname(file)), path.basename(file), not_translated
+            )
+        )
+
+
+def audit(file, en_file):
+    en_json = load(open(en_file))
+    translation_json = load(open(file))
+    print_result(get_missing(en_json, translation_json), get_not_translated(en_json, translation_json), file)
+
+
+def main():
+    for en_file in glob(path.join(DIR, EN_PATH)):
+        for file in glob(path.join(DIR, ALL_PATH)):
+            if path.basename(en_file) == path.basename(file) and file != en_file:
+                audit(file, en_file)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/website/docs/add_edit_translations.md b/website/docs/add_edit_translations.md
new file mode 100644
index 00000000..63aff32c
--- /dev/null
+++ b/website/docs/add_edit_translations.md
@@ -0,0 +1,38 @@
+## Adding new locales to i18n
+
+This guide will help you add a new locale to the `i18n` setup.
+
+### Prerequisites
+
+- An up-to-date branch with the `main` branch.
+- Familiarity with `i18n`, `react-i18next`, and `next-i18next` libraries is beneficial.
+
+### Adding a new language
+
+1. Determine the language and country codes using `ISO 639-1`. For example, `en` for English.
+1. Create a new directory within the `public/locales` directory using the language and country codes as the name, for
+   example `en`.
+1. Copy all the files from the `en` directory into the newly created directory.
+1. Edit the copied the text in the copied files with the desired language.
+1. Add the new language to the list in `next-i18next.config.js` if it does not already exist.
+1. Follow the instructions in [Website README](<[README.md](../../../website/README.md)>) to run and test the new
+   language by changing the active locale in the application and verifying that all translated keys are properly
+   displayed.
+1. Commit your changes and open a pull request against the `main` branch for review.
+
+### Editing existing translation files
+
+When editing existing translations, follow these rules:
+
+1. English translations are required, and other locales fall back to them.
+1. Keep translation keys in alphabetical order.
+1. Add all translations for higher-level components (e.g. `Layout.ts`) in `common.json` to prevent hydration issues.
+1. Add reused translation keys in `common.json`.
+1. Split translation files into separate files by feature or route.
+
+### Finding missing translations
+
+A script can be used to find missing and potentially untranslated locale files. Run the script from the root dir using
+`python scripts/frontend-development/find-missing-locales.py`.
+
+If you have any questions or need further assistance, please reach out.