1k-i18n
OneKey i18n and Lokalise workflow for searching, adding, updating, pulling, and using translation keys. Verify the target project and full locale coverage; never edit generated translation files.
How do I install this agent skill?
npx skills add https://github.com/onekeyhq/app-monorepo --skill 1k-i18nIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides safe guidelines for managing internationalization and translations. It emphasizes using predefined translation keys and prohibits direct modification of auto-generated files.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
2/2 files flagged
What does this agent skill do?
Internationalization (i18n)
Guidelines for internationalization and translation management in OneKey.
Critical Restrictions
ABSOLUTELY FORBIDDEN (auto-generated files):
// ❌ NEVER modify these files - they are AUTO-GENERATED
// @onekeyhq/shared/src/locale/enum/translations.ts
// @onekeyhq/shared/src/locale/json/*.json
// ❌ NEVER hardcode text strings
<Text>Confirm</Text>
// ✅ CORRECT - Always use translation keys
import { ETranslations } from '@onekeyhq/shared/src/locale';
intl.formatMessage({ id: ETranslations.global__confirm })
Consequences of violation:
- Translation system corruption
- Loss of translation work
- Build failures in i18n pipeline
- Breaking localization for international users
Existing Keys First
Search locally and remotely before creating a key. Reuse a key only when its meaning, placeholders, and UI context match.
For any Lokalise create or update:
- Verify the actual target project name and ID before mutating it.
- Fetch that project's configured languages; do not infer them from an environment-variable name.
- Prefer repository scripts and credential wrappers.
yarn opis the default;keychainandoenvvariants are supported alternatives. - A configured Lokalise MCP or Lokalise Web may be used for an existing translation, but the same project and language checks still apply.
- After the remote change, sync locally with
yarn i18n:pull,yarn i18n:pull:keychain, oryarn i18n:pull:oenv.
Key Shape Mapping
The same translation may appear in 3 different shapes depending on where you look:
Lokalise / MCP source key: global::contact_us
Pulled local JSON key: global.contact_us
Generated enum member: ETranslations.global_contact_us
For newer suffix-style keys, Lokalise and local JSON usually match:
Lokalise / MCP source key: address_book__action
Pulled local JSON key: address_book__action
Generated enum member: ETranslations.address_book__action
Query guidance:
- Lokalise / MCP: prefer the exact source key. Legacy namespaced keys often use
::. - Local
yarn i18n:search: searches pulleden_US.json, so legacy keys should be queried with., while newer suffix-style keys should be queried with__. - Code usage: refer to the generated
ETranslationsmember with_.
End-to-End Delivery Requirements
For any task that creates or updates a translation:
- Check the current branch and worktree before pulling generated files.
- Resolve credentials without printing tokens.
- Retrieve
GET /projects/{project_id}and confirm the returned project name and ID match the intended target. - Retrieve
GET /projects/{project_id}/languagesand record its exactlang_isovalues. - Search for the exact key in that verified project before creating it.
- Use
yarn i18n:addfor a missing key. It only createsen_USand optionalzh_CNsource translations; it does not complete the remaining locales. - Ensure the key has valid translations for every checked-in locale. The repository currently has 19 locale JSON files.
- Pull generated files, verify the enum and all locale JSON files, and inspect the full generated diff for unrelated remote updates.
- Wire the generated
ETranslationsmember in code and validate placeholder consistency.
Do not silently skip a repository locale because the target project uses a
different code format. Map repository locale names to the project's configured
lang_iso values. If the project genuinely lacks a required language, stop
before upload and report the mismatch.
The completion report must state the verified project name/ID, covered locale set, pull command used, generated-file scope, and any unrelated keys brought in by the pull. Review code changes separately from generated locale changes.
Read i18n.md before performing any remote Lokalise
mutation or i18n:pull. It contains the project preflight, current 19-locale
set, translation-record update flow, and generated-diff verification.
Quick Reference
Using Translations in Components
import { useIntl } from 'react-intl';
import { ETranslations } from '@onekeyhq/shared/src/locale';
function MyComponent() {
const intl = useIntl();
return (
<SizableText>
{intl.formatMessage({ id: ETranslations.global__confirm })}
</SizableText>
);
}
Using formatMessage Outside Components
import { appLocale } from '@onekeyhq/shared/src/locale/appLocale';
import { ETranslations } from '@onekeyhq/shared/src/locale';
const message = appLocale.intl.formatMessage({
id: ETranslations.global__cancel,
});
Translation Workflow
- Search first
- Local search:
yarn i18n:search "global.contact_us"oryarn i18n:search "address_book__action"
- Local search:
- Verify the target — confirm project name/ID and fetch exact project languages
- Search remotely — query the exact source key, such as
global::contact_us, in that verified project - If the key already exists, update it in Lokalise by translation record
- If it is a new key, add it via
yarn i18n:addusing the suffix-style underscore format - Complete every repository locale — do not stop after
en_US/zh_CN - Pull and inspect — verify the key everywhere and call out unrelated generated changes
- Use in code:
{intl.formatMessage({ id: ETranslations.global_contact_us })}
New Key Naming Pattern
semantic_key__type
Examples:
- send__title
- confirm_send__action
- enter_send_amount__desc
- transaction_failed__msg
Detailed Guide
For comprehensive i18n guidelines and the end-to-end Lokalise workflow, see i18n.md.
Topics covered:
- Translation management restrictions
- Using translations in components
- Translation key naming conventions
- Target project and language verification
- Full 19-locale coverage
- Safe Lokalise create/update and pull flow
- Generated-diff inspection
- Locale handling and fallbacks
- Code examples
Key Files
| Purpose | File Path |
|---|---|
| Translation enum (auto-generated) | packages/shared/src/locale/enum/translations.ts |
| Locale JSON (auto-generated) | packages/shared/src/locale/json/ |
| App locale | packages/shared/src/locale/appLocale.ts |
| Default locale | packages/shared/src/locale/getDefaultLocale.ts |
| Lokalise add script | development/scripts/i18n/i18n-add.js |
| Lokalise pull script | development/scripts/i18n/i18n-pull.js |
Related Skills
/1k-coding-patterns- Date formatting with locale support/1k-coding-patterns- General coding patterns
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/onekeyhq/app-monorepo/1k-i18n">View 1k-i18n on skillZs</a>