# 国际化

组件内部自带的提示文本（如搜索占位符、复制成功提示、清空按钮等）走统一的语言环境管理，没有把中文或英文硬编码在每个组件里。随包默认内置的语言是英文（`en`）和简体中文（`zh-CN`）。在 TypeScript 类型定义中，`AstryxLocale` 指的就是这两种内置语言代码。

通常只需在应用的顶层根组件提供一次语言配置，下层所有子组件就可以自动通过 `useAstryxLocale` 和 `useAstryxMessages` 读取当前的语言文本。未配置时，默认使用英文。

```ts
import { provideAstryxLocale } from '@astryx-vue/core/locale'

// 全局配置为简体中文
provideAstryxLocale('zh-CN')
```

与国际化相关的常用函数（如 `provideAstryxLocale`、`useAstryxLocale`、`useAstryxMessages`、`useLocale`、`useTranslator`、`normalizeLocale`、`loadAstryxCatalog` 和 `useCollator`）均可以从 `@astryx-vue/core/locale` 引入，在包根 `@astryx-vue/core` 也有重新导出。仅日历相关的底层格式化工具 `formatCalendarMonth` 和 `weekdayNames` 专属于 `@astryx-vue/core/locale`。

`normalizeLocale` 函数会自动标准化常见的语言标签：
- 把 `zh`、`zh-CN`、`zh-Hans` 等归一化为 `zh-CN`，对上内置的简体中文文案；
- 其他标签只规范大小写，地区信息会保留，例如 `en-gb` 变成 `en-GB`、`ja-jp` 变成 `ja-JP`。日期、数字、排序因此按这个地区的习惯来；
- 内置文案只分「简体中文」和「其他」两种：`en`、`en-GB`、`fr-FR` 这些没有交 `messages` 的语言，组件文字都用英文；
- 空值或无法解析的标签会自动回退到英文 `en`。

## 在组件之外读语言和翻译（useLocale、useTranslator）

组件里的格式化（日期、数字、相对时间、排序）都读最近一层 `InternationalizationProvider` 的语言，不读 `navigator.language`。你自己写的格式化函数也应该这样：

```ts
import { useLocale, useTranslator } from '@astryx-vue/core/locale'

const { locale } = useLocale()
const { t } = useTranslator()

// 语言变了，这两个值会跟着变
const label = computed(() => new Intl.DateTimeFormat(locale.value).format(date))
const announce = () => t('@astryx.pagination.pageAnnounce', { current: 3 })
```

`t` 收的是原版的 `@astryx.*` 键，返回当前语言的成品文案。键认不出来时原样返回这个键，方便一眼看出写错了。在事件回调里也可以直接调用。

## 支持中文和英文以外的更多语言

原版 Astryx 在 `packages/core/locales` 目录下存放了约 30 份基于 React Intl 格式的语言 JSON 文件（包含 `ja-JP`、`zh-TW`、`ar-SA` 等）。我们将这些官方多语言资源完整同步在包内的 `locales/` 目录下。

你可以借助 `loadAstryxCatalog` 函数，将这些原版 JSON 转换映射为组件库可用的 `AstryxMessages` 结构，然后作为第二个参数传递给 `provideAstryxLocale`：

```ts
import { loadAstryxCatalog, provideAstryxLocale } from '@astryx-vue/core/locale'
import catalog from '@astryx-vue/core/locales/ja-JP.json'

// 加载日语语言包
const loaded = loadAstryxCatalog('ja-JP', catalog)
provideAstryxLocale(loaded.locale, loaded.messages)
```

加载器具备容错处理：
- 如果原版 JSON 中某些键名在 Vue 版中未被使用，会保存在返回对象的 `unmapped` 属性中，避免数据丢失；
- 如果某项文本在 JSON 中缺失，会自动回退到内置英文，涉及的字段路径记录在 `fallbackFields` 中；
- 如果组件需要某项文本但外部 JSON 根本没有提供，会记录在 `missingKeys` 中。

> **提示**：内置英文和原版 `en.json` 逐字一致，`pnpm check:i18n-catalog` 会守着这一点。内置的 `zh-CN` 是我们自己写的中文，比原版 `zh-CN.json` 更口语一些，请不要用原版的那份去覆盖它。其他语言才建议通过该加载器引入。
>
> 如果只调用 `provideAstryxLocale('ja-JP')` 而没有传入转换后的 `messages`，那么组件内部的日期和字母排序会按日语规则运行，但组件自带的提示语仍会保持英文；同理，传入 `zh-TW` 也不会自动偷懒降级为简体中文。

如果你是维护者，需要同步原版最新语言包，运行 `node scripts/vendor-astryx-locales.mjs` 即可，它默认拉原版 `main` 的最新提交；需要复现某一次抓取时，把提交号当参数传进去。实际用到的提交号写在 `locales/SOURCE.json`，来源与开源许可证说明记录在 `packages/core/THIRD_PARTY_NOTICES.md` 中。

拉完后跑一次 `pnpm check:i18n-catalog`（`pnpm check` 里也会跑）。它会检查：

- 内置 `en` 和 `zh-CN` 的每个字段都有，而且形状一样；
- 内置文案用上了原版的每个占位符，内置英文和原版英文逐字一致；
- 29 种语言的每句译文都能解析，占位符的名字和写法（`{name}`、`number`、`plural`、`select`）和英文原文一致，没有过期的键；
- 原版新增的每个键，要么已经接进 `packages/core/src/locale/upstream/`，要么在 `scripts/i18n-catalog/coverage.mjs` 里写明了为什么暂不接入。

## 按当前语言排序字符串（useCollator）

在不同国家和语言下，文字的排序习惯差异很大（例如拼音排序与注音、假名排序）。`useCollator` 函数返回一个基于当前语言环境的 `Intl.Collator` 实例，并包装在 Vue 的 `computed` 中。未设置语言时默认按英文处理：

```ts
import { useCollator } from '@astryx-vue/core/locale'

const collator = useCollator({ numeric: true })
// 按照当前语言环境自然排序
items.sort((a, b) => collator.value.compare(a.name, b.name))
```

## 区分组件内置文案与业务文案

`AstryxMessages` 仅管理组件库内置的通用文案（如「复制」、「清除」等）。你在业务中自己写进组件的文字（例如 `` 传入的 `label`），是由你的业务代码完全掌控的，切换组件库语言不会去修改你的业务文字。

文档站顶部切换的中英文，是通过 VitePress 路由实现的两个完全独立的页面树（分别位于根路径 `/` 和 `/en/`），属于文档网站层面的多语言；而文档中的实时组件示例，则会自动根据当前页面的文档语言调用 `provideAstryxLocale`。

## 从右往左排版与伪语言测试

阿拉伯语、希伯来语、波斯语这些语言从右往左写。这件事组件库已经做了大半，但有两步得你自己做。

### 第一步：告诉组件方向

`InternationalizationProvider` 有一个 `dir` 属性，取 `'ltr'` 或 `'rtl'`。不传的话，方向由 `locale` 推出来：`ar-SA`、`he` 得到 `rtl`，其余得到 `ltr`。

推导靠 `getLocaleDirection()`。它先问浏览器要 `Intl.Locale` 的书写方向；浏览器还不支持时，退回一张内置的从右往左语言清单（`ar`、`he`、`fa`、`ur`、`ps`、`sd` 等）。认不出来的标签按 `ltr` 处理，不会报错。

```vue
<script setup lang="ts">
import { InternationalizationProvider } from '@astryx-vue/core/InternationalizationProvider'
</script>

<template>
  <!-- 方向由 locale 推出来 -->
  <InternationalizationProvider locale="ar-SA">
    <App />
  </InternationalizationProvider>

  <!-- 语言是英文，但强制按从右往左排版：用来测布局 -->
  <InternationalizationProvider locale="en" dir="rtl">
    <App />
  </InternationalizationProvider>
</template>
```

自己在组合式函数里要读方向，用 `useLocaleDirection()`，它返回一个 `ref`，语言变了会跟着变：

```ts
import { useLocaleDirection } from '@astryx-vue/core/InternationalizationProvider'

const direction = useLocaleDirection()
// 'ltr' 或 'rtl'
```

### 第二步：自己设置 DOM 的 dir

`dir` 属性只决定 Astryx 组件读到的方向，它不会去改 DOM。这一步必须你来做，通常写在 `<html>` 上：

```ts
import { getLocaleDirection } from '@astryx-vue/core/InternationalizationProvider'

// 浏览器里切换语言时同步一次
document.documentElement.dir = getLocaleDirection(locale.value)
document.documentElement.lang = locale.value
```

漏掉这一步的后果：文字仍然从左往右排，标点和混排文本的方向不对，滚动条位置也反。组件内部的镜像是对的，页面上看着还是反的。

### 组件做了什么

- **内外边距和定位。** 组件样式大量使用逻辑属性：`padding-inline-start`、`margin-inline-end`、`inset-inline-start`。方向一反，这些值自动换边，不需要第二套样式。
- **文字对齐。** 用的是 `text-align: start` 和 `end`，不是 `left` 和 `right`。
- **少数位置单独处理。** 提示框、悬停卡片的 `start`、`end` 弹层在 `[dir='rtl']` 下会翻边；面包屑的分隔斜杠会跟着改方向；滑杆的握把用 `:dir(rtl)` 单独修正。
- **键盘方向键。** 日历读 `document.documentElement.dir`：从右往左时，左右方向键的作用是反的。滚动相关的计算也会按书写方向换轴。

这也解释了为什么第二步不能省：日历和滚动这类逻辑读的就是 DOM 上的 `dir`，不是 provider 的值。

### 伪语言测试

最省事的做法不是装语言包，而是两步：

1. 把 `dir` 设成 `rtl`，`<html dir="rtl">` 也设上，看整个页面还站不站得住。
2. 把文案换成一段更长的假文字，看布局会不会被撑破。

第二步用 `overrides` 属性。它按语言覆盖指定键，只改你写的那几条：

```vue
<script setup lang="ts">
import { InternationalizationProvider } from '@astryx-vue/core/InternationalizationProvider'

// 键和原版语言包一致。这里故意写长，用来挤布局
const pseudo = {
  '@astryx.table.noData': '没有找到任何数据，这句话被故意写得很长很长，用来检查单元格会不会被撑破',
}
</script>

<template>
  <InternationalizationProvider locale="zh-CN" :overrides="pseudo">
    <App />
  </InternationalizationProvider>
</template>
```

### 检查清单

方向改成 `rtl`、文案拉长以后，逐条看这几件：

- 数字、价格、日期还是从左往右读，没有跟着整段反过来。
- 图标和文字的顺序对了：返回箭头指向右边，下拉箭头在文字的左边。
- 输入框里的光标从右边开始，占位文字靠右对齐。
- 侧边栏和侧面板换到了右边，拖拽手柄的方向也跟着反了。哪一处没换，就是那一处写死了 `left` 或 `right`。
- 长文案下按钮不换行，表格列不塌，标题不溢出色块。
- 表格里的数字列仍然右对齐（数字本身从右往左写会很怪）。

这套检查在深色模式、窄屏下各跑一遍，差不多就够用了。