AlexandrAI AGENTS.md
agents-md

nk304 Locales Package Agent Guide

Project-specific AGENTS.md guidance for the nk304 locales package, 12 language bundles, dynamic loading, normalization aliases, fallback behavior, and localization tests.

AGENTS.md

Guidance for coding agents working on nk304 packages/locales. This package exports reusable locale bundles and language normalization helpers.

Project Overview

packages/locales contains locale bundles for 12 languages, dynamic bundle loading, supported-language metadata, aliases for language normalization, and tests for language behavior. It is shared infrastructure for product text, but the web runtime also has its own locale-loader source of truth. Do not assume this package automatically controls every visible string.

Supported languages are English, Korean, Japanese, Traditional Chinese, Simplified Chinese, Spanish, Brazilian Portuguese, French, German, Vietnamese, Indonesian, and Thai. The package default is English.

Project Map

  • src/languages.ts defines supported language ids, label keys, aliases, normalization, and default language.
  • src/loader.ts dynamically imports the requested locale bundle and falls back to English.
  • src/locales/.ts and language subfolders contain domain-specific bundles.
  • Domain bundle files include common, auth, openChat, inventory, project, admin, profile, errors, and download.
  • src/languages.test.mts validates language helper behavior.
  • package.json builds with tsup and tests with the Node test runner.

Setup Commands

bashpnpm --filter @nk304/locales run test
pnpm --filter @nk304/locales run build

Before assuming a string comes from this package, inspect the runtime consumer:

bashrg "getLocaleBundle|normalizeLanguage|locales" apps packages

Change Rules For Agents

  • Add or update English keys first unless the task is a dedicated localization pass.
  • Keep all language bundle shapes aligned with the English bundle type.
  • Update aliases when supporting a new language id or regional variant.
  • Keep dynamic import cases synchronized with SUPPORTED_LANGUAGES.
  • Do not remove a key from one locale unless all consumers and all bundles are updated.
  • Avoid machine translation churn during unrelated feature work. Mark missing non-English propagation as follow-up unless the task requests it.
  • Respect web runtime fallback guidance when package defaults and app defaults differ.

Verification

bashpnpm --filter @nk304/locales run test
pnpm --filter @nk304/locales run build

If visible web strings change, also run the web locale coverage or closest component tests that read those keys.

Security Notes

Locale strings are rendered in user interfaces. Do not embed raw HTML, private service names, real emails, tokens, internal endpoints, or operator-only instructions inside translation values.

PR Checklist

  • English source text and all required bundle shapes are aligned.
  • Language aliases and loader cases match.
  • Consumer source of truth was checked before changing fallback behavior.
  • Locale tests pass.