flutter-localization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Localization Setup

本地化配置

Use Flutter's built-in
```
flutter_localizations
```
and
```
intl
```
packages
Enable
```
generate: true
```
in
```
pubspec.yaml
```
for automatic code generation

Configure

l10n.yaml

at project root:

yaml

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-class: AppLocalizations
nullable-getter: false

使用Flutter内置的
```
flutter_localizations
```
和
```
intl
```
包
在
```
pubspec.yaml
```
中启用
```
generate: true
```
以开启自动代码生成

在项目根目录配置

l10n.yaml

：

yaml

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-class: AppLocalizations
nullable-getter: false

ARB File Structure

ARB文件结构

Place all
```
.arb
```
files in
```
lib/l10n/
```

Use

app_{locale}.arb

naming convention (e.g.,

app_en.arb

app_es.arb

app_hi.arb

)

The template ARB file (

app_en.arb

) MUST contain

metadata for every key:

json

{
  "loginTitle": "Sign In",
  "@loginTitle": { "description": "Title on the login screen" },
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": { "description": "Item count with pluralization", "placeholders": { "count": { "type": "int" } } }
}

Key naming: Use

featureName_context

format (e.g.,

settings_title

login_emailHint

)

Group keys by feature in the ARB file with comment separators

所有
```
.arb
```
文件放置在
```
lib/l10n/
```
目录下

使用

app_{locale}.arb

命名规范（例如

app_en.arb

、

app_es.arb

、

app_hi.arb

）

模板ARB文件（

app_en.arb

）必须为每个键包含

开头的元数据：

json

{
  "loginTitle": "Sign In",
  "@loginTitle": { "description": "Title on the login screen" },
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": { "description": "Item count with pluralization", "placeholders": { "count": { "type": "int" } } }
}

键名命名：使用

功能模块名_上下文

格式（例如

settings_title

、

login_emailHint

）

在ARB文件中通过注释分隔符按功能模块对键进行分组

Usage Rules

使用规则

Access strings via
```
context.l10n.keyName
```
using a
```
BuildContext
```
extension
STRICTLY prohibit hardcoded user-facing strings anywhere in the codebase
STRICTLY prohibit using
```
.l10n
```
in
```
initState()
```
or outside the widget tree —
```
context
```
must be available
For date/time/number formatting, use
```
intl
```
package formatters with the current locale

通过
```
BuildContext
```
扩展，使用
```
context.l10n.keyName
```
访问字符串
严格禁止在代码库的任何位置硬编码面向用户的字符串
严格禁止在
```
initState()
```
中或widget树之外使用
```
.l10n
```
——必须保证
```
context
```
可用
对于日期/时间/数字格式化，结合当前区域设置使用
```
intl
```
包的格式化工具

Plural & Select Forms

复数与选择形式

Use ICU plural syntax for countable items:

{count, plural, =0{...} =1{...} other{...}}

Use ICU select syntax for gender/category:

{gender, select, male{...} female{...} other{...}}

Always include the
```
other
```
case as a fallback

对可数项目使用ICU复数语法：

{count, plural, =0{...} =1{...} other{...}}

对性别/分类场景使用ICU选择语法：

{gender, select, male{...} female{...} other{...}}

始终包含
```
other
```
分支作为兜底

RTL Support

RTL支持

Use
```
Directionality
```
and
```
TextDirection
```
-aware widgets
Prefer
```
EdgeInsetsDirectional
```
over
```
EdgeInsets
```
for padding/margins

Use

start

end

instead of

left

right

MainAxisAlignment

and

CrossAxisAlignment

Test with RTL locales during widget testing

使用支持
```
Directionality
```
和
```
TextDirection
```
的组件
内边距/外边距优先使用
```
EdgeInsetsDirectional
```
而非
```
EdgeInsets
```

在

MainAxisAlignment

和

CrossAxisAlignment

中使用

start

end

替代

left

right

在组件测试时使用RTL区域设置进行测试

Adding a New Language

新增一门语言

Create
```
app_{locale}.arb
```
with all keys translated
Run
```
flutter gen-l10n
```
(or rely on auto-generation)
Add the
```
Locale
```
to
```
supportedLocales
```
in
```
MaterialApp
```
Verify with widget tests using the new locale

创建
```
app_{locale}.arb
```
文件，完成所有键的翻译
运行
```
flutter gen-l10n
```
（或依赖自动生成机制）
在
```
MaterialApp
```
的
```
supportedLocales
```
中添加对应的
```
Locale
```
使用新区域设置编写组件测试验证功能