ocp-plugin-i18n-scripts

Reusable i18n/localization scripts for OpenShift Console dynamic plugins. Automates the workflow of extracting translation keys, uploading to Memsource/Phrase for professional translation, and downloading the results back into your project.

Who should use this

Any OpenShift Console dynamic plugin that needs to support multiple languages via the Memsource/Phrase translation platform. This package replaces the need to copy i18n-scripts/ directories between plugin repositories.

Prerequisites

• Node.js >= 18
• jq installed (brew install jq on macOS, yum install jq on RHEL)
• memsource-cli installed and configured (for upload/download commands only)

Installing memsource-cli

DIRECTORY="${HOME}/git/memsource-cli-client/"
mkdir -p "$DIRECTORY" && cd "$DIRECTORY"
python3 -m venv --system-site-packages .memsource
source .memsource/bin/activate
pip install -U pip setuptools pbr memsource-cli

Create ~/.memsourcerc:

source ${HOME}/git/memsource-cli-client/.memsource/bin/activate
export MEMSOURCE_URL="https://cloud.memsource.com/web"
export MEMSOURCE_USERNAME=<your-username>
export MEMSOURCE_PASSWORD="<your-password>"
export MEMSOURCE_TOKEN=$(memsource auth login --user-name $MEMSOURCE_USERNAME --password "${MEMSOURCE_PASSWORD}" -c token -f value)

Run source ~/.memsourcerc before using upload/download commands.

Setup

1. Install the package

npm install --save-dev ocp-plugin-i18n-scripts

2. Create i18n-scripts.config.json in your project root

{
  "pluginName": "plugin__your-plugin-name",
  "projectTitle": "[YourProject $VERSION] UI Localization - Sprint $SPRINT/Branch $BRANCH",
  "templateId": "169304",
  "languages": ["ja", "zh-cn", "ko", "fr", "es"],
  "languageAliases": { "zh-cn": "zh" },
  "pluralOverrides": {}
}

3. Create i18next-parser.config.ts in your project root

This config tells i18next-parser how to extract translation keys from your source files. The CustomJSONLexer extracts keys matching the %...% pattern from plugin extension files. It must be inlined (not imported from a file) because i18next-parser bundles the config as ESM.

import type { UserConfig } from 'i18next-parser';

const CustomJSONLexer = {
  extract(content: string): { key: string }[] {
    const keys: { key: string }[] = [];
    try {
      const parsed = JSON.parse(content) as Record<string, unknown>;
      const scan = (obj: unknown): void => {
        if (typeof obj === 'string') {
          const match = obj.match(/^%(?<key>.+)%$/u);
          if (match?.groups?.['key']) {
            keys.push({ key: match.groups['key'] });
          }
        } else if (Array.isArray(obj)) {
          obj.forEach(scan);
        } else if (obj && typeof obj === 'object') {
          Object.values(obj).forEach(scan);
        }
      };
      scan(parsed);
    } catch {
      // not valid JSON, skip
    }
    return keys;
  },
};

const config: UserConfig = {
  createOldCatalogs: false,
  defaultNamespace: 'plugin__your-plugin-name',
  defaultValue(_locale, _namespace, key: string | undefined): string {
    return key ?? '';
  },
  keySeparator: false,
  lexers: {
    default: ['JsxLexer'],
    json: [CustomJSONLexer] as unknown as UserConfig['lexers'],
    tsx: [
      {
        componentFunctions: ['Trans', 'ForkliftTrans'],
        lexer: 'JsxLexer',
      },
    ],
  } as UserConfig['lexers'],
  locales: ['en', 'es', 'fr', 'ja', 'ko', 'zh'],
  namespaceSeparator: '~',
  sort: true,
};

export default config;

Adjust the following for your plugin:

• defaultNamespace -- set to your plugin's i18next namespace (must match pluginName in config)
• componentFunctions in the tsx lexer -- add any custom Trans components your plugin uses
• locales -- must match the languages in i18n-scripts.config.json (use filesystem names, e.g., zh not zh-cn)

4. Add npm scripts to your package.json

{
  "scripts": {
    "i18n": "i18next \"./src/**/*.{js,jsx,ts,tsx}\" ./plugin-extensions.ts [-oc] -c ./i18next-parser.config.ts && ocp-i18n-defaults && ocp-i18n-fix-plurals && ocp-i18n-replace-br",
    "export-pos": "ocp-i18n-export-pos",
    "i18n-to-po": "ocp-i18n-to-po",
    "po-to-i18n": "ocp-i18n-po-to-i18n",
    "memsource-upload": "ocp-i18n-memsource-upload",
    "memsource-download": "ocp-i18n-memsource-download",
    "i18n-dummy-locale": "ocp-i18n-dummy-locale"
  }
}

Configuration Reference

| Field | Required | Description | |-------|----------|-------------| | pluginName | Yes | The i18next namespace (e.g., plugin__forklift-console-plugin). Used to derive locale JSON and PO filenames. | | projectTitle | No | Memsource project title template. Supports $VERSION, $SPRINT, $BRANCH variables. | | templateId | No | Memsource project template ID. | | languages | Yes | Array of target language codes (e.g., ["ja", "zh-cn", "ko", "fr", "es"]). | | languageAliases | No | Maps language codes to filesystem directory names (e.g., {"zh-cn": "zh"}). Used when the Memsource language code differs from the i18next locale directory. | | pluralOverrides | No | Key-value pairs to fix auto-generated pluralizations. Runs after set-english-defaults. Example: {"{{count}} virtual machine selected_other": "{{count}} virtual machines selected"}. |

Command Reference

Key extraction and post-processing

| Command | Description | |---------|-------------| | ocp-i18n-defaults | Auto-populates English locale values after i18next-parser extracts keys. Handles plural forms via the pluralize package. | | ocp-i18n-fix-plurals | Applies plural overrides from config to fix edge cases in auto-generated pluralizations. | | ocp-i18n-replace-br | Replaces   HTML entities with regular spaces across all locale JSON files. |

Memsource/Phrase workflow

| Command | Description | |---------|-------------| | ocp-i18n-export-pos | Exports English locale JSON to PO files for all configured languages. | | ocp-i18n-memsource-upload | Exports PO files and uploads them to Memsource. Usage: npm run memsource-upload -- -v VERSION -s SPRINT | | ocp-i18n-memsource-download | Downloads translated PO files from Memsource and converts them back to locale JSON. Usage: npm run memsource-download -- -p PROJECT_ID |

Conversion utilities

| Command | Description | |---------|-------------| | ocp-i18n-to-po | Converts i18next JSON to PO format. Usage: ocp-i18n-to-po -f FILENAME -l LANGUAGE | | ocp-i18n-po-to-i18n | Converts PO files back to i18next JSON. Usage: ocp-i18n-po-to-i18n -d DIRECTORY -l LANGUAGE |

Development utilities

| Command | Description | |---------|-------------| | ocp-i18n-dummy-locale | Generates dummy locale files for es and fr by wrapping English strings with visual markers. Useful for testing locale switching without real translations. |

Typical Workflow

1. Develop features with t('...') translation keys
2. Run: npm run i18n                              (extract keys, set defaults)
3. Commit locale file changes
4. Run: source ~/.memsourcerc                     (authenticate)
5. Run: npm run memsource-upload -- -v 2.12 -s 1  (upload to Phrase)
6. Translators review and confirm translations in Phrase
7. Run: npm run memsource-download -- -p PROJECT_ID (download translations)
8. Translations are auto-committed to locales/<lang>/ directories

Migration from local i18n-scripts/

If your project already has a local i18n-scripts/ directory copied from kubevirt-plugin:

1. Install this package: npm install --save-dev ocp-plugin-i18n-scripts
2. Create i18n-scripts.config.json with your plugin's settings
3. Update package.json scripts to use ocp-i18n-* commands (see Setup step 3)
4. Verify outputs match: run both old and new commands, diff the generated PO/JSON files
5. Remove the local i18n-scripts/ directory
6. Remove local-only devDependencies if no longer needed: minimist, pluralize, i18next-conv

License

Apache-2.0