Command Palette

Search for a command to run...

开发者指南

文档

关于 LocaleDB 数据、管道和架构所需了解的一切。

概览

LocaleDB 是一个全面的开源本地化百科全书，专为构建国际应用程序的开发人员设计。

250+ 国家

114 种语言

161 种货币

9,415 个机场

核心功能

  • 来自权威来源的全面数据 (CLDR, World Bank, mledoze, libphonenumber, OpenFlights)
  • 静态生成 - 无需运行时数据库
  • MIT 许可且由社区驱动
  • 支持 11 种语言，包括阿拉伯语的 RTL 支持

入门

克隆代码库并在几分钟内开始探索区域数据。

# 克隆代码库
git clone https://github.com/ozkurkculer/localedb.git
cd localedb

# 安装依赖项
pnpm install

# 从源下载原始数据
pnpm update:data

# 处理并生成 JSON 文件
pnpm build:data

# 启动开发服务器
pnpm dev

数据管道

LocaleDB 通过多阶段管道处理来自多个权威来源的数据。

1

外部来源

CLDR, mledoze, World Bank, libphonenumber, OpenFlights (MWGG)

2

下载原始数据

pnpm update:data 将文件下载到 data/ 子目录

3

原始数据文件

存储在 data/ 中的 JSON, CSV 和 XML 文件

4

处理与合并

pnpm build:data 根据优先级规则合并源

5

生成的 JSON

单独的国家、语言和货币文件

6

静态站点生成

Next.js 构建 5,868+ 个静态页面

数据源优先级

当多个来源提供相同的字段时，我们使用一致的优先级系统：

  • •国家名称：CLDR > mledoze > SimpleLocalize
  • •人口：World Bank > mledoze > SimpleLocalize
  • •电话数据：libphonenumber XML (权威)

数据模式

国家、语言和货币 JSON 文件的详细结构。

国家模式

data/countries/{CODE}.json
basics

名称、首都、坐标、大洲、人口、面积、语言、国旗表情

codes

ISO 3166, BCP-47, FIFA, IOC, FIPS 以及其他国际代码

currency

代码、符号、位置、分隔符、小数位数、模式、示例

dateTime

日期/时间格式（完整、长、中、短）、一周的第一天、时区

numberFormat

小数/千位分隔符、数字分组、数字系统

phone

呼叫代码、模式、格式规则、用户号码长度

addressFormat

格式模板、邮政编码正则表达式及示例

locale

书写方向、度量系统、温度标度、纸张尺寸、驾驶侧

airports

包含 IATA, ICAO, 坐标, 时区的机场数组

语言模式

data/languages/{code}.json
code

ISO 639-1 代码

name

英文名称

nativeName

本地名称

direction

文本方向 (ltr 或 rtl)

countries

使用该语言的国家代码数组

货币模式

data/currencies/{CODE}.json
code

ISO 4217 代码

name

货币名称

symbol

货币符号

symbolPosition

before 或 after

separators

小数和千位分隔符

decimalDigits

标准小数位数

pattern

格式化模式

example

格式化示例

countries

使用此货币的国家代码数组

项目结构

关键目录及其用途。

localedb/
├── data/                    # 生成的 JSON 文件和原始源数据
│   ├── countries/           # 250 country JSON files
│   ├── languages/           # 114 language JSON files
│   ├── currencies/          # 161 currency JSON files
│   ├── _index_*.json        # Lightweight indices
│   └── _meta.json           # Build metadata
├── scripts/                 # 数据管道脚本 (update-data.ts, build-data.ts)
│   ├── update-data.ts       # Download raw data
│   ├── build-data.ts        # Process & generate JSON
│   └── generate-changelog.ts
├── src/
│   ├── app/[locale]/        # Next.js pages (i18n)
│   ├── components/          # React components
│   ├── lib/                 # Data access functions
│   ├── config/              # Site & nav config
│   └── i18n/                # Internationalization setup
└── messages/                # 11 种语言的翻译文件

脚本参考

用于数据管理和开发的可用命令。

CommandDescription
pnpm update:data从所有外部来源下载原始数据
pnpm update:data cldr worldbank仅下载特定来源
pnpm build:data处理原始数据并生成 JSON 文件
pnpm dev启动开发服务器
pnpm build生产构建（静态站点生成）
npx tsx scripts/check-i18n.ts检查并自动填充缺失的翻译键
pnpm version patch提升版本并自动生成更新日志

贡献数据

如何为 LocaleDB 贡献更正和改进。

贡献工作流程

  1. 1Fork GitHub 代码库并克隆到本地机器
  2. 2在 build-data.ts 中编辑源优先级或向在上游源提交更正
  3. 3通过编辑 messages/{lang}.json 并运行 check-i18n 添加翻译
  4. 4提交 Pull Request，每个 PR 一个更改，并附上官方来源链接

指南

  • 每个 Pull Request 一个更改
  • 始终链接到官方来源 (CLDR, 政府网站, ISO 标准)
  • 运行 pnpm build:data 以验证您的更改是否正确合并
  • 清晰、描述性的提交信息

国际化

LocaleDB 支持 11 种语言，并计划支持更多。

支持的语言

英语、土耳其语、中文、印地语、西班牙语、法语、阿拉伯语、孟加拉语、葡萄牙语、俄语、日语

翻译文件

所有翻译都存储在 messages/{lang}.json 文件中

RTL 支持

对阿拉伯语 (ar) 和其他 RTL 语言的完全从右到左支持

添加新语言

  1. 1创建一个新 messages/{lang}.json 文件
  2. 2翻译 messages/en.json 中的所有键
  3. 3将区域代码添加到 src/i18n/routing.ts
  4. 4运行 npx tsx scripts/check-i18n.ts 以验证完整性