多语言与从右往左

爬山虎的界面和用户写的内容可能是任何语言。这一章规定：每种文字用什么字体、行高和字距怎么随文字变、阿拉伯文这类从右往左的语言怎么镜像，以及数字、日期和长文本的写法。规则都落在 token 里，Web 和 Flutter 读同一份数据。

支持的语言

先告诉界面用的是哪种语言

字体、行高、字距和镜像全部跟着语言标签走，所以第一步是把语言写对。

Web：在 <html> 上写 lang 和 dir，用 @bostonivy/design 的 applyLocale：

import { applyLocale } from '@bostonivy/design';

applyLocale(document.documentElement, 'ar'); // <html lang="ar" dir="rtl">

• 已知语言的内容块（比如一段日文评论）可以单独加 lang，它会用自己那一组的字体和行高。
• 用户写的任务标题、评论、描述，语言事先不知道：元素加 dir="auto"，按第一个强方向字符决定方向。

Flutter：MaterialApp 配好 locale、supportedLocales 和 GlobalMaterialLocalizations 等代理，Directionality 会跟着语言自动变成从右往左。主题要把同一个 locale 传进去：

MaterialApp(
  locale: locale,
  supportedLocales: supportedLocales,
  localizationsDelegates: GlobalMaterialLocalizations.delegates,
  theme: bostonIvyTheme(BiStyle.clean, Brightness.light, locale: locale),
  darkTheme: bostonIvyTheme(BiStyle.clean, Brightness.dark, locale: locale),
);

跟随系统语言时，用 WidgetsBinding.instance.platformDispatcher.locale，并在 didChangeLocales 里重建主题。

字体回退

品牌字体（Inter、Fredoka、JetBrains Mono、Silkscreen）只负责拉丁字母。其他文字交给系统自带的字体，客户端不打包：一套中日韩字体就有 10 到 20 MB，而且系统字体和用户在别的应用里看到的一致。

每个字体栈都按这个顺序拼起来：

1. 风格的品牌字体
2. 界面语言那一组的系统字体
3. 其余各组的系统字体（一段文字里混着几种文字时，每种文字都有固定的字体）
4. 彩色 emoji
5. system-ui，然后是通用字族（sans-serif 或 monospace）

第 5 步的 system-ui 不能省。实测 macOS 上的 Chrome：品牌字体是等宽的 JetBrains Mono 时，如果没写明阿拉伯文字体，浏览器会挑一个等宽的阿拉伯文字体来回退，字母一个个断开。所以阿拉伯文组里写了 macOS 自带的 Geeza Pro。

完整的字体名单在 bostonivy-tokens.json 的 core.script.<组>.font，emoji 在 core.font.emoji。

为什么中日韩要分组：同一个汉字码位在简体、繁体、日文、韩文里字形不同，比如「骨」「直」「說」。浏览器和 Flutter 都靠语言标签挑字形，语言标签不对，日文界面里就会出现中文字形。

三种风格怎么保持一致

• 整段换字体，不在一个词里混字体。 Fredoka 和 Silkscreen 缺土耳其文（ğ ş İ）、越南文、西里尔字母、波兰文、捷克文、罗马尼亚文、匈牙利文（ő ű）和希腊字母。界面是这些语言时，萌虎整体换成 Inter，像素的标题和计时器整体换成 JetBrains Mono。如果不换，「Değiştir」里的 ğ 会落到另一种字体上。名单在 style.sticker.font 和 style.pixel.font.display 的 substituteFor 里。
• 像素风格不用点阵中文。 12 到 13px 的点阵汉字只有 12×12 的格子，「藤」「警」这种笔画多的字会糊成一团；开源点阵字体的字数也不够，生僻字会掉回黑体，同一行里一半点阵一半黑体反而更乱；汉字也不是 JetBrains Mono 字宽的整两倍，对不齐等宽网格。
• Silkscreen 只有大写形状，只用于英文和数字。中文、日文、阿拉伯文这些没有大小写的文字，text-transform: uppercase 不起作用，也不需要。

行高与字距

天城文、孟加拉文、泰文、阿拉伯文的符号会伸到拉丁字母上下方很远的地方，越南文的大写字母上叠两层符号。行高不够时，多行文字会互相碰到；单行省略的元素（overflow: hidden）还会直接把字形切掉。每组都有一个行高下限，三种风格的行高只会被抬到这个下限，不会被压低。

依据一栏的数值是用 HarfBuzz 排版常见界面文字、量出来的墨迹范围。下限的算法：品牌字体的行盒在基线上下留出的空间，要能装下墨迹的最高点和最低点。

• Web：--type-* 写成 max(原行高, 字号 × var(--leading-min))，字距写成 原字距 × var(--tracking-scale)。例如青藤的任务标题是 14 / 20，在阿拉伯文界面里变成 14 / 24.5。
• Flutter：bostonIvyTheme(..., locale:) 里，TextStyle.height 取 max(原比例, BiScript.leadingMin)，letterSpacing 乘以 BiScript.trackingScale。
• 行高变高以后，任务行、按钮这些容器要用最小高度（min-height、ConstrainedBox），不要写死高度。现有组件已经这样做。
• 字号不随语言变，最小 12px。
• 不用斜体表示强调：中日韩、阿拉伯文、天城文都没有真正的斜体，浏览器会把字形硬拉斜。强调用字重。

从右往左

阿拉伯语、波斯语、乌尔都语、希伯来语界面整体镜像：阅读从右边开始，界面也从右边开始。

布局

一律写逻辑方向，不写左右：

跟着镜像的：侧栏移到右边，详情面板移到左边；勾选框在行首，也就是右边；看板的列从右往左排，甘特图的时间从右往左走；进度条从右往左填充；返回箭头指向右边；头像叠放的方向反过来；Android 上左滑、右滑对应的操作对调。在树和横向列表里，键盘的 ← → 键的含义也随方向对调，按 WAI-ARIA 的写法实现。

不镜像的：时钟和计时器圆环（永远顺时针）；播放、停止这类媒体控件；数字本身（永远从左往右写）；代码、快捷键、URL；Logo、吉祥物和插画。

图标

35 个图标里，有 7 个指向阅读方向，或者画的是从起始边排起的文字和布局，从右往左时要水平翻转：

其余图标不翻转，包括 timer（时钟）、play stop（媒体）、repeat（循环）、check checklist（勾）、search、attachment、priority（旗子是实物）。

• Web：给需要翻转的图标加 class="bi-mirror-rtl"。tokens.css 在 dir="rtl" 下把它镜像过来，名单是 mirroredIcons。组件库的 Icon 已经自动加上这个类。
• Flutter：BiIcon 读 Directionality，BiIcons.mirrorInRtl 为真时自动翻转，不用额外处理。
• 名单在 bostonivy-tokens.json 的 $extensions.app.bostonivy.rtl.mirrorIcons。新增图标时先判断要不要翻转。

三种风格的装饰

双向混排

从右往左的文本里夹着数字和拉丁字母时，「#42」「00:42:18」「v0.3.0」「report.pdf」这类片段会被前后文字拉到错误的位置。规则是把它们隔离开：

• Web 用 <bdi> 或 dir="ltr" 包起来。
• Flutter 在字符串两头加 U+2066 和 U+2069（LRI、PDI），或者把这一段放进单独的 Directionality。

用户输入的任务标题和评论：Web 用 dir="auto"；Flutter 用 intl 的 Bidi.detectRtlDirectionality 判断方向，再传给 TextField 和 Text 的 textDirection。

数字与日期

一律交给平台的本地化接口，不要自己拼字符串：Web 用 Intl.DateTimeFormat、Intl.NumberFormat、Intl.RelativeTimeFormat、Intl.PluralRules，Flutter 用 intl 包的 DateFormat、NumberFormat 和 MaterialLocalizations。

同一时间点（10月20日 18:00）在列表里的短格式，由 Intl.DateTimeFormat 生成：

文本长度

按英文设计，给翻译留余量：德语、俄语、法语通常比英文长 30%，两三个词的短标签可能长一倍；中日韩短 30% 到 50%，但字更高。

断行规则：

• 德语、俄语里长的复合词：hyphens: auto，前提是 lang 写对。
• URL 和文件名：overflow-wrap: anywhere。
• 韩语按词断行：word-break: keep-all。中文和日语用 line-break: strict，标点不出现在行首。
• 泰语词与词之间没有空格，浏览器和 Flutter 按词典断行，不要手动插空格。

测试方法：每个界面至少用德语、阿拉伯语、日语各过一遍。Android 打开开发者选项里的伪语言 en-XA（文字拉长并加上重音符号）和 ar-XB（强制从右往左）；Web 用脚本把文案拉长 40% 再看一遍。

Token 与变量一览