i18n 实践及过程FAQ

By Patrick
3 min

目录

一起推进产品的i18n，打造国际化的一流产品。
这个文档大家都可以编辑补充，有问题请dm @PatrickChoo

💁‍♀️ i18n Key 推荐命名方式

根据过往实践 i18n 经验，推荐按照以下方式进行i18n Key命名：

🔡 使用4个元素进行key名定义

顺序

元素

解释

例子

顺序

元素

解释

例子

1

控件

该词条位于的模块的名称

title标题
form表单
modal 弹窗
msg 提示消息

2

位置 (*可选的二级归集，少用)

该词条位于页面的位置

dapp_list_tabDApp信息块的列表TAB

3

词条内容

该词条本身的含义

recovery_phrase助记词

4

属性(可选)

要求以及属性

abbr缩写
hint表单提示
desc描述
body正文
lowercase全小写 
uppercase全大写
capitalize 首字母大写化

模块/流程 后方 使用 __ 双下划线 进行分隔 元素内的词组使用 _ 单下划线 进行分隔

将4个元素进行组合，获得Key名称。 模块 / 流程__位置(可选)__词条内容_属性(可选)

词条内容需要注意

词条内容应尽量使用文字中的内容，因为这样无论key和代码上都比较直观。

如果标题和描述属于同一个信息块面，词条内容元素可写作：
title__whats_recovery_phrase
title__whats_recovery_phrase_desc

如果信息块面没有标题，需要将内容写到 key 名上，可使用模块名 wallet__ 进行归纳：
title__enter_12_18_24_words_recovery_phrase

模糊的词条key名称会导致重复引用率低，或是创建时容易发生key name冲突，代码上无法清晰反应词条内容，例如：

独立的长文字：请勿导入OneKey硬件钱包助记词
🙅 不好：title__attention（这样以后可能变成了 attention1, attention2, attention3）
👌 推荐：title__dont_import_onekey_hardware_wallet_recovery_phrase

词条内容编写时可以使用 DeepL，让它协助你快速将中文内容转成英文

请看以下 Key 名称例子。

🌰 Key 名称例子

Key

词条内容

命名解释

Key

词条内容

命名解释

app__version

版本

全局使用的词汇

使用 app__ 归集前缀提高Key重复使用率

action__create

创建

按钮文字

使用 action__ 归集前缀提高Key重复使用率

title__create_account

创建账户

标题

title__create_account_desc

选择以下方式

标题下的描述

tab__discover

发现

底部导航的发现Tab

tab__dapp_list__hot

热门

“发现” 里 “DApp列表” 的 “热门” tab，为了几个并列的词列在一起，加入了二级自定义归集 dapp_list_tab

content__privacy_policy_1
content__privacy_policy_2

关于「隐私权政策」的段落1
关于「隐私权政策」的段落2

 

🗂 归集有可能重复使用的词条

使用约定的前缀归集可能重复使用的词条，避免i18n Key散落，提高Key重复使用率。
⚠️ 在归集前缀后方直接加词条内容，例如：
🙅 不好：action__home_cancel
👌 推荐：action__cancel（其他地方也可共用这个Key）

🌟 目前已定义的前缀

我们定义了以下的前缀，如非必要请不要添加新的前缀。

前缀

归集内容

例子

前缀

归集内容

例子

app__

App全局词

app__app_nameApp名称 "OneKey"
app__version 版本

action__

按钮及动作

action__cancel 按钮字“取消”
action__confirm按钮字"确认"

form__

表单内容

form__email表单的内容标题 “电子邮箱”
form__password_hint 填空下方的密码要求提示
form__password_placeholder 表单内输入前空格内的提示
form__security_uppercase 表单头使用全大写字母显示 SECURITY

msg__

提示信息

msg__invalid_address“地址不正确，请检查再试”

modal__

Alert / Action Sheet / Dialog

modal__invalid_address
modal__invalid_address_desc
modal__invalid_address_desc_write_your_contents_here (假如同一个标题有多个描述，后方加描述内容)

title__

页面标题

title__restore_master_wallet
title__restore_master_wallet_desc

content__

内容材料

content__slogan__safe_and_easy_to_use slogan内容“安全与易用”

language__

语言

language__simplified_chinese 简体中文
language__traditional_chinese_hong_kong 繁体中文(香港)
language__english_united_states 英语(美国)

coin__

币种

coin__bitcoin 比特币 Bitcoin
coin__ethereum 以太坊 Ethereum
如果是 BTC、ETH 等直接使用简写无需翻译的地方，请勿创建词条

apimsg__

API 输出的提示

apimsg__service_unavailable 服务不可用

词条内容大小写的处理

一般短语的内容，我们使用单词首字母大写的方式进行处理，例如 Recovery Phrase。
如果短语内容需要全小写，或者全大写的场景，则在Key的后方加入：
_lowercase 全小写
_uppercase 全大写


📝产品设计师如何参与i18n

使用 Lokalise 进行软件 i18n

在产品设计定稿后，产品设计师需要在 Lokalise 进行词条录入，提供 i18n Keys 表格给开发。 开发过程中发生Key，需要同步给开发。

全员i18n！

🧑‍💻 iOS / Android 开发过程如何参与i18n

iOS i18n 同步脚本

脚本调用 Lokalise CLI 工具，将词条下载到项目目录下。

1.安装 Lokalise cli工具
brew tap lokalise/cli-2 brew install lokalise2
2.安装 SwiftGen
brew install swiftgen
3.在工程目录下，执行脚本
./i18n_update.sh

在同步过后，就可以在项目中调入Key了。

由于XCode处理i18n词条，不如Android Studio那样优雅，达到自动提示的效果需要生成枚举。
./i18n_update.sh 脚本中已经包含了生成枚举的动作，使用 Localizable.即可看到自动提示。

🤔 FAQ及实践统一

Key命名补充

是否可以在词条KeyName的内容部分使用缩写？

🙅 form__set_your_pwd
虽然这样建立 key 少打几个字，但是我们还是应该在词条key名上写上概括内容的完整单词，方便在代码中进行检索，如果内容不统一，比如出现 pwd和password还有pw，代码中搜索相关内容可能会有需要搜索多次的麻烦。
👌 form__set_your_password

内容有变量怎么办？

例如："2 个人在线" dapp__int_people_online 使用Lokalise的 Universal Placeholders 通用占位符 会自动将位置留出，开发时传入变量，即可置入对应的位置。下载翻译文件时会对不同平台进行变量格式处理。 [%s], [%1$s], [%s:name] – String [%i], [%1$i], [%i:name] – Integer [%f], [%.2f], [%1$.2f], [%.2f:name] – Float

Key Name中使用 str int float 占位

类型例子Key 名称翻译内容字符串ETH节点、BTC节点、DOT节点wallet__str_nodes英文：[%s] Nodes
中文：[%s] 节点
其中
[%s] 是字符串变量
[%6$s] 限制6位字符的字符串(比较少用)
[%s:coin] 在某些支持变量名的平台上，将显示变量的名称coin，不支持的就不显示整数22 个人在线dapp__int_people_online英文：[%i] People Online
中文：[%i] 人在线
其中
[%i] 是整数变量
[%2$i] 限制2位数字的整数浮点数价格 0.00238 BTCwallet__price_float_str英文：Price [%f.5f] [%s]
中文：价格 [%.5f] [%s]
第一变量传入价格浮点数类型，第二变量传入字符串 BTC

一般来说 str 类型是比较常使用的，即使是遇到带数字的场景。具体需要类型可询问开发。

例如 在 转账页面 的处理 慢、适中、快选项卡底部的预估时间

Key Name英文内容中文内容form__about_str_minAbout [%s] min约 [%s] 分钟

当无数据时传入 "-"，有数据的时候传入数据字符串“fast.time”（分钟时间的数字），即显示出对应的效果： 无数据：约 - 分钟 有数据：约 30 分钟 ⚠️ 注意 Key名照常写就可以，不要在Key名内增加placeholder
🙅 form__about_[%s]_min
👌 form__about_str_min

Placeholder 和相邻内容之间的空格处理 form__about_str_min 的英语翻译內容：
🙅 About[%s]min （效果： About20min）
👌 About [%s] min （效果： About 20 min）

请注意内容区域不要省略 [ ] 中括号，不然无法自动转换成对应平台的格式。

有些语言的复数形式比较复杂怎么办？

某些语言例如俄罗斯语，在不同的数量的时候会有不同的复数形式。 点击词条Key Name打开Key设置，选择高级 - PLURAL 功能，将自动列出不同语言需要的复数形式的填空。

内容的英文单词是全小写或者全大写怎么办？

后方加入_uppercase全大写 _lowercase 全小写 👌form__security_uppercase

页面出现了散落的短句怎么给Key命名？

使用内容 content__ 前缀前缀进行内容归纳 👌content__you_have_created_these_wallet_accounts_before_select_accounts_that_you_want_to_restore

标题有多行怎么办？

使用_multiline属性词，用于 title__ 下发生多行内容的情况。

title__的开头的词条默认单行，但为了文字排版，标题词条有时候需要包含换行，此时写上 _multiline 属性词在结尾，提示此词语是属于包含换行的词条。 好处：

在代码中能清晰获知此词条会发生换行区分出有换行和没有换行的词条

例： 原词条：有 OneKey，安全和好用当然可以兼得。 这个句子在大标题处发生换行后，力量感变少了，所以我修改了大熊的文案。

👌title__security_and_ease_of_use_multiline
安全、易用 二者兼得 界面出现大标题时，可以放心使用换行来增加排版的美观程度。（iOS有很多很好的例子）

 

产品文案需要注意

删除非必要的描述信息

对用户使用没有帮助的、冗余重复描述的内容，应直接删除。 需要从 UI 源头把关，克制无用信息的产生。

弹窗标题直接说重点

好的弹窗标题应该能让人扫视即可获得概要信息，不应用作多余修饰，尽量不要只写 “提示”、“警告”。

Title - Request / What’s happening - 标题直接写请求，不要害怕使用长句 Desc - Why / Solution - 为什么以及解决方式

Outlook for iOS 例： 标题：Allow “Outlook” to use your location? 描述：This will help you book conference rooms, find nearby places, show travel times, and display weather info. 动作: * Allow Once * Allow While Using App * Don’t Allow

英文标题介词放心省略

当你想写 Set the Password，标题可以直接写 Set Password。短小精悍。 描述字里的句子则完整地写出：Set your password. 按钮 Add a New Device
👌 Add New Device
按钮 Activate the Device
👌 Activate Device

英文提示不用客气

不加 Please 更符合英语直接了当的使用习惯，太多 Please 变得不直观。 例：两次输入密码不一致，请重新输入。
🙅 The two passwords are different. Please re-enter them.
👌 Passwords did not match. Try again.

克制使用 "成功…" 的提示文案

尽量使用 “已…” 替代 “成功”。功能正常运作是常态，不需要特别庆祝。

例：msg__added_to_your_favorites
🙅 成功加入您的收藏夹！Successfully added to your favorites!
👌 已加入您的收藏夹 Added to your favorites

统一使用您作为第二人称

关于App内使用“你”还是“您”，我记得在刚刚入行实习时候鹅厂内部BBS里面还有过专门的讨论，鹅厂以年轻化的产品为主，崇尚平等沟通的文化，所以在产品设计中大范围地使用你作为产品文案中的第二人称。 而 OneKey 作为资产管理的产品，给用户多一些被服务的感受是可以的，毕竟礼多人不怪。 所以我们统一用 您作为第二人称代称吧！

文案大小写的注意

品牌词，例如：

  • OneKey (O大写，K大写)

  • OneKey Touch

  • OneKey Mini

  • OneKey Pro

术语词，例如：

  • KeyStore (参考Google)

  • DApp

  • Backup 是名词，Back Up 是动作

图片素材i18n

i18n 除了文本词条，图片素材也需要考虑国际化。
比如首页的快速上手教程入口图，如果必须做成图片，那就需要输出多个国家语言的图片资源。
所以比较推荐使用代码绘制图片素材中的文字，图片素材预留文字位置。