{"id":18938225,"url":"https://github.com/wechat-miniprogram/miniprogram-i18n","last_synced_at":"2025-04-15T14:57:59.050Z","repository":{"id":44793629,"uuid":"161425296","full_name":"wechat-miniprogram/miniprogram-i18n","owner":"wechat-miniprogram","description":"小程序国际化方案 / The internationalizational (i18n) library for wechat miniprogram","archived":false,"fork":false,"pushed_at":"2021-09-30T08:11:51.000Z","size":152,"stargazers_count":141,"open_issues_count":11,"forks_count":36,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-15T14:57:50.568Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wechat-miniprogram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-12T03:04:01.000Z","updated_at":"2025-03-24T03:20:27.000Z","dependencies_parsed_at":"2022-09-09T08:51:09.429Z","dependency_job_id":null,"html_url":"https://github.com/wechat-miniprogram/miniprogram-i18n","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechat-miniprogram%2Fminiprogram-i18n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechat-miniprogram%2Fminiprogram-i18n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechat-miniprogram%2Fminiprogram-i18n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechat-miniprogram%2Fminiprogram-i18n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wechat-miniprogram","download_url":"https://codeload.github.com/wechat-miniprogram/miniprogram-i18n/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249094938,"owners_count":21211836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T12:13:45.731Z","updated_at":"2025-04-15T14:57:59.009Z","avatar_url":"https://github.com/wechat-miniprogram.png","language":"TypeScript","readme":"# miniprogram-i18n\n[![CircleCI](https://circleci.com/gh/wechat-miniprogram/miniprogram-i18n.svg?style=svg)](https://circleci.com/gh/wechat-miniprogram/miniprogram-i18n)\n\n微信小程序的国际化 (i18n) 方案。为小程序的双线程模型定制，使用 WXS 环境作为 WXML 国际化的运行时，很大程度上减少了国际化在小程序中运行所需的开销。使用上，只需在 WXML 或 JavaScript 中调用翻译函数即可获得翻译文本。i18n 文本可以定义在任意位置，在构建过程中会被统一打包至指定路径。\n\n## 文档\n\n- [快速入门](./docs/quickstart.md)\n- [接口文档](./docs/api.md)\n- [Gulp插件配置文档](./docs/gulp.md)\n- [example 示例工程文档](./examples/README.md)\n\n## 安装\n\n该方案目前需要依赖 Gulp 并且对源文件目录结构有一定的要求，需要确保小程序源文件放置在特定目录下（例如 src/ 目录）：\n\n1. 首先在项目根目录运行以下命令安装 gulp 及 miniprogram-i18n 的 gulp 插件。\n\n```\nnpm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml\n```\n\n2. 在小程序运行环境下安装国际化运行时并在开发工具\"构建npm\"。\n\n```\nnpm i -S @miniprogram-i18n/core\n```\n\n3. 在项目根目录新建 gulpfile.js，并编写构建脚本，可参考 [examples/gulpfile.js](./examples/gulpfile.js)。具体配置详见 [Gulp插件配置文档](./docs/gulp.md)。\n\n## 使用\n\n### 定义 i18n\n\n对所需翻译文本进行定义。例如在 `src/i18n/en-US.json` 中定义：\n\n```\n{\n  \"greeting\": \"hello {toWhom}!\"\n}\n```\n\n其他语言文本在相应语言文件下进行定义即可。\n\n### 使用 i18n\n\n定义好 i18n 文本之后，即可在 WXML 及 JavaScript 文件中使用了。\n\n#### WXML\n\n```html\n\u003c!-- src/pages/index/index.wxml --\u003e\n\u003cview\u003e{{ t('greeting', { toWhom: 'i18n' }) }}\u003c/view\u003e\n```\n\n另外，需要在 WXML 对应的 JavaScript 文件中进行一些定义，这里以 Component 构造器为例。\n\n```js\n// src/pages/index/index.js\nimport { I18n } from '@miniprogram-i18n/core'\n\nComponent({\n  behaviors: [I18n]\n})\n```\n\n最终，实际运行时，以上 WXML 会被解析成如下片段并显示。\n\n```\n\u003cview\u003ehello i18n!\u003c/view\u003e\n```\n\n### JavaScript\n\n在 JavaScript 调用接口可能也有文本需要进行国际化处理，此时可以使用 i18n 接口进行文本翻译。\n\n```js\n// src/pages/index/index.js\n\nComponent({\n  behaviors: [I18n],\n  attached() {\n    const text = this.t('greeting', { toWhom: 'JavaScript' })\n    console.log(text)\n  }\n})\n```\n\n更多使用细节请参考以下文档：\n\n- [快速入门](./docs/quickstart.md)\n\n- [接口文档](./docs/api.md)\n- [Gulp插件配置文档](./docs/gulp.md)\n\n### 特性\n\n目前 miniprogram-i18n 仅支持纯文本及文本插值，后续会对其他 i18n 特性进行支持。\n\n#### 文本插值\n\n```js\n{\n  \"key\": \"Inserted value: {value}\"\n}\n```\n\n```js\ni18n.t('key', { value: 'Hello!' })  // Inserted value: Hello!\n```\n\n为了方便调用深层嵌套的对象，当前支持使用 `.` 点语法来访问对象属性。\n\n```json\n{\n   \"dotted\": \"Nested value is: { obj.nested.value }\"\n}\n```\n\n```js\nconst value = {\n  obj: {\n    nested: {\n      value: 'Catch you!'\n    }\n  }\n}\ni18n.t('dotted', value)  // Nested value is: Catch you!\n```\n\n#### select 语句\n\n```json\n{\n  \"key\": \"{gender, select, male {His inbox} female {Her inbox} other {Their inbox}}\"\n}\n```\n\n```js\ni18n.t('key', { gender: 'male' })    // His inbox\ni18n.t('key', { gender: 'female' })  // Her inbox\ni18n.t('key')                        // Their inbox\n```\n\nselect 语句支持子语句文本插值：\n\n```\n{\n  \"key\": \"{mood, select, good {{how} day!} sad {{how} day.} other {Whatever!}}\"\n}\n```\n\n```js\ni18n.t('key', { mood: 'good', how: 'Awesome'  })  // Awesome day!\ni18n.t('key', { mood: 'sad', how: 'Unhappy'  })   // Unhappy day.\ni18n.t('key')                                     // Whatever!\n```\n\n\u003e 注：select 语句支持子句嵌套 select 语句\n\n其他尚未支持的特性有：\n\n- Pseudo 字符串\n- 单复数处理\n- 日期、数字、货币处理\n- 定义文件的命名空间\n- 支持 WXML 与 JavaScript 独立定义\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwechat-miniprogram%2Fminiprogram-i18n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwechat-miniprogram%2Fminiprogram-i18n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwechat-miniprogram%2Fminiprogram-i18n/lists"}