Check i18n/L10n keys and values

i18n-check is a Python package to automate the validation of keys and values of your internationalization and localization processes.

Developed by the activist community, this process is meant to assure that development and i18n/L10n teams are in sync when using JSON based localization processes. The action can be expanded later to work for other file type processes as needed.

Note

For the GitHub action please see activist-org/i18n-check-action.

Contents

• Conventions
• How it works
  • Arguments
  • Checks
• Configuration
• Development environment
• Contributors

Conventions ⇧

activist i18n keys follow the following conventions that are enforced by i18n-check:

• All key base paths should be the file path where the key is used prepended with i18n.
  • Starting i18n keys with a common identifier allows them to be found within checks
• If a key is used in more than one file, then the lowest common directory followed by _global is the base path
• Base paths should be followed by a minimally descriptive content reference
  • Only the formatting of these content references is checked via i18n-check
• Separate base directory paths by periods (.)
• Separate all directory and file name components as well as content references by underscores (_)
• Repeat words in file paths for sub directory organization should not be repeated in the key

Note

An example valid key is:

Key: "components.component_name.CONTENT_REFERENCE"

File: components/component/ComponentName.ext

How it works ⇧

Arguments ⇧

You provide i18n-check with the following arguments:

• src-dir: The path to the directory that has source code to check
• i18n-dir: The directory path to your i18n files
• i18n-src: The name of the i18n source file

Checks ⇧

From there the following checks are ran across your codebase:

• invalid-keys: Does the include i18n keys that are not within the source file?
• key-identifiers: Does the source file have keys that don't match the above format or name conventions?
  • Rename them so i18n key usage is consistent and their scope is communicated in their name.
• unused-keys: Does the source file have keys that are not used in the codebase?
  • Remove them so the localization team isn't working on strings that aren't used.
• non-source-keys: Do the target locale files have keys that are not in the source file?
  • Remove them as they won't be used in the application.
• repeat-values: Does the source file have repeat values that can be combined into a single key?
  • Combine them so the localization team only needs to localize one of them.

Each of the above checks is ran in parallel with directions for how to fix the i18n files being provided when errors are raised. Checks can also be disabled in the workflow via options passed in the configuration YAML file.

Configuration ⇧

The following details the .18n-check.yaml configuration file, with a further example being the configuration file for this repository that we use in testing.

src-dir: frontend
i18n-dir: frontend/i18n
i18n-src: frontend/i18n/en.json

checks:
  - invalid-keys: true
  - key-identifiers: true
  - non-source-keys: true
  - repeat-values: true
  - unused-keys: true

file-types-to-check: [.ts, .js]
directories-to-skip: [frontend/node_modules]
files-to-skip: []
warn-on-nested-i18n-src: true

Common additional arguments for using specific web frameworks can be found in the dropdowns below:

Vue.js

file_types_to_check: [.vue]
directories_to_skip: [.nuxt, .output, dist]

Development environment ⇧

1. First and foremost, please see the suggested IDE setup in the dropdown below to make sure that your editor is ready for development.

Important

Suggested IDE setup

VS Code

Install the following extensions:

• charliermarsh.ruff
• streetsidesoftware.code-spell-checker

2. Fork the i18n-check repo, clone your fork, and configure the remotes:

Note

Consider using SSH

Alternatively to using HTTPS as in the instructions below, consider SSH to interact with GitHub from the terminal. SSH allows you to connect without a user-pass authentication flow.

To run git commands with SSH, remember then to substitute the HTTPS URL, https://github.com/..., with the SSH one, [email protected]:....

• e.g. Cloning now becomes git clone [email protected]:<your-username>/i18n-check.git

GitHub also has their documentation on how to Generate a new SSH key 🔑

# Clone your fork of the repo into the current directory.
git clone https://github.com/<your-username>/i18n-check.git
# Navigate to the newly cloned directory.
cd i18n-check
# Assign the original repo to a remote called "upstream".
git remote add upstream https://github.com/activist-org/i18n-check.git

• Now, if you run git remote -v you should see two remote repositories named:
  • origin (forked repository)
  • upstream (i18n-check repository)

3. Create a virtual environment, activate it and install dependencies:

   # Unix or MacOS:
   python3 -m venv venv
   source venv/bin/activate
   
   # Windows:
   python -m venv venv
   venv\Scripts\activate.bat
   
   # After activating venv:
   pip install --upgrade pip
   pip install -r requirements-dev.txt

You're now ready to work on i18n-check!

Note

Feel free to contact the team in the Development room on Matrix if you're having problems getting your environment setup!

Contributors ⇧

Thanks to all our amazing contributors! ❤️