worldref

worldref

**用阿拉伯语、英语或两种语言呈现所有国家的信息：**名称、国籍、首都、货币、语言、时区、拨号代码、电话验证、地址格式和行政区划。一个数据集，可用于 JSON、CSV、SQL、TypeScript、Python、Swift、Kotlin、Dart、PHP、Go 和 C#，也适用于 AI Agent（MCP）。

العربية · 网站和搜索演示 · 最佳实践 · 字段参考 · 数据来源

import { countries, search, parsePhone, byIso2 } from "worldref";

byIso2("SA").name_ar;                       // "السعودية"
byIso2("SA").nationality.nationality_ar_f;  // "سعودية"
search(countries, "الامارات", "ar")[0].iso2; // "AE"  (ignores «ال», hamza and tashkeel)
parsePhone("٠٥٠١٢٣٤٥٦٧", byIso2("SA"));     // { e164: "+966501234567", valid: true, mobile: true, ... }

为什么选择 worldref

• **原生支持阿拉伯语。**提供常用简称（السعودية，而非音译）、阳性和阴性国籍称谓（سعودي / سعودية）；搜索时会忽略「ال」、附标元音符号、延长符和不同形式的 hamza；支持在任何地方使用阿拉伯-印度数字和波斯数字；排序键可在所有平台实现正确的阿拉伯语字母顺序。
• **支持单语或双语。**每个文件都提供三种构建版本：双语版（name_ar、name_en）、仅阿拉伯语版（name）和仅英语版（name）。
• **可用的电话字段。**涵盖每个国家的拨号代码、有效号码长度、手机前缀和精确验证模式；解析共享拨号代码（+1、+7、+44……），并支持输出国际格式（E.164）。
• **表单或应用所需信息一应俱全：**官方名称、首都、带符号的货币（包括新的沙特里亚尔符号）、官方语言、每周起始日和周末、首选历法（包括 Umm al-Qura）、邮政编码规则、地址模板、紧急电话号码、插头类型和电压、FIFA 和 IOC 代码，以及 ISO 3166-2 行政区划。
• **数据有据可查，而非凭空猜测。**优先采用官方来源（Unicode CLDR、Google libphonenumber、世界银行、IANA、ITU 和政府来源）。每列的来源都列于 data/sources.json。缺失值记为 null，绝不猜测或使用机器翻译。

安装

已发布到 npm、PyPI、pub.dev、Packagist、NuGet 和 MCP Registry。Swift、Kotlin 和 Go 可直接从此仓库安装。

技术栈	安装方式
JavaScript、TypeScript（Web、Node 20.10+、React Native、Bun、Deno）	npm i worldref
CDN（无需构建）	https://cdn.jsdelivr.net/npm/[email protected]/data/worldref.json
Swift（iOS、macOS）	Swift Package Manager：https://github.com/arj-89/worldref，版本从 1.1.2 起，产品为 WorldRef
Kotlin、Android	JitPack：maven("https://jitpack.io")，然后执行 implementation("com.github.arj-89:worldref:v1.1.2")
Python	pip install worldref
Dart、Flutter	dart pub add worldref（Flutter：flutter pub add worldref）
PHP、Laravel	composer require arj-89/worldref
Go	go get github.com/arj-89/worldref/[email protected]
C#、.NET	dotnet add package WorldRef
任意语言	JSON、CSV 和 SQL（Postgres、MySQL、SQLite），位于 data/ 和发布页面
AI Agent	MCP 服务：npx -y worldref mcp（在 MCP Registry 中的条目为 io.github.arj-89/worldref）
无需安装	单个国家：https://arj-89.github.io/worldref/api/v1/sa.json

每个语言文件夹都有自己的 README 和使用示例：python、Swift、kotlin、dart、php、go、csharp。

只使用所需内容

• 数据拆分为多个共享 iso2 键的模块：core、nationality、phone、currency、geo、locale、address、travel、sports，以及 subdivisions。可在 data/modules/ 中找到。
• 每个模块提供 3 种构建版本：.json（阿拉伯语和英语）、.ar.json（仅阿拉伯语）、.en.json（仅英语）。
• **JS/TS：**仅导入所用模块，打包工具也只会打包该文件：

  import phone from "worldref/data/modules/phone.json" with { type: "json" };
  import { parsePhone } from "worldref/helpers";
  

• **其他语言：**只加载所需的模块文件。data/worldref.json 包含全部数据。
• 单个国家，无需安装：https://arj-89.github.io/worldref/api/v1/{iso2}.json。
• 缺失值为 null（或空列表）。请将其视为未知值，切勿自行填入。
• 在同一主版本中，字段不会重命名或移除。

使用示例

国家选择器（先显示用户所在国家，再按界面语言的字母顺序排列）：

import { countries, sortCountries, search } from "worldref";
const list = sortCountries(countries, "ar", "SA");          // السعودية first, then Arabic order
const hits = search(countries, userQuery, "ar");            // names, aliases, ISO codes, +966 / 00966 / 966

显示：旗帜、界面语言的国家名称，然后是拨号代码。在阿拉伯语界面中，将拨号代码隔离为从左向右书写（<bdi dir="ltr">+966</bdi>）。

电话字段（存储国际格式号码，以及用户选择的国家）：

const p = parsePhone(input, byIso2(pickedIso2), countries);
if (p?.valid && p.mobile) save({ phone: p.e164, phone_country: p.iso2 });

国籍字段（仅显示有国籍信息的条目：国家，以及台湾、香港和澳门）：

const options = countries.filter((c) => c.nationality.nationality_en);
const label = (c, female) => (female ? c.nationality.nationality_ar_f : c.nationality.nationality_ar_m);

**数据库初始化：**运行 data/sql/postgres.sql（或 mysql.sql、sqlite.sql）。该脚本会创建 countries 和 subdivisions。

最佳实践

以下规则已内置于全部八个软件包的辅助函数中，并由 tests/vectors.json 中的共享测试锁定。请使用这些辅助函数；如果自行编写，请严格遵循这些规则。

搜索（normalize()、search()）

• 对查询和名称两侧采用相同的规范化方式。
• 阿拉伯语：删除每个词开头的「ال」（不只是第一个词）；移除 tashkeel（fatha、damma、kasra、sukun、shadda、tanween）和 tatweel（ـ）；将 أ إ آ ٱ 视为 ا，将 ة 视为 ه，将 ى 视为 ي，将 ؤ 视为 و，将 ئ 视为 ي。因此，「الإمارات」、「امارات」和「الأمارات」都能找到阿联酋。
• 拉丁文字：忽略大小写和重音符号，并将标点视为空格，因此「cote d'ivoire」能找到 Côte d’Ivoire。
• 数字：在进行任何其他处理前，先将阿拉伯-印度数字（٠١٢٣٤٥٦٧٨٩）和波斯数字（۰۱۲۳۴۵۶۷۸۹）转换为西方数字。
• 匹配两种语言的名称和别名、ISO 代码（SA、SAU），以及带或不带「+」或「00」的拨号代码（+966、00966、966）。

排序（sortCountries()）

• 优先显示用户所在国家：先取用户资料中的国家，否则取设备地区；若两者都没有，则不固定任何国家。
• 然后按 sort_ar 或 sort_en 使用普通字符串比较排序。不要使用区域排序规则（Intl.Collator("ar")、localizedStandardCompare）：它们都不会忽略「ال」，因此所有以「ال」开头的名称都会聚在 ا 下。

显示

• 依次显示旗帜、界面语言对应的名称和拨号代码。
• 在阿拉伯语界面中，将拨号代码和任何拉丁文字隔离，并在界面中从左到右显示（<bdi dir="ltr">+966</bdi>，或 U+2066 ... U+2069）。数据中不包含双向文本标记。
• 在两种语言的界面中都使用西方数字（0-9）。
• 网页端使用 flag_svg：Windows 不会绘制旗帜表情符号。
• 货币：显示 symbol（沙特里亚尔符号为 U+20C1）；若字体不支持这个新符号，则回退为 symbol_fallback（ر.س）。

电话字段（parsePhone()、formatNational()）

• 接受用户输入的任何格式：阿拉伯或西方数字、空格、连字符、开头的 0、「+」或「00」。
• 将国际格式（e164）与用户选择的 iso2 一起存储。共享拨号代码（+1、+7、+44、+599……）无法仅凭号码还原到某个国家。
• 使用 mobile_pattern 验证手机号码。对于 mobile_distinguishable 为 false 的地区（美国、加拿大），不要仅因号码看起来不像手机号码而拒绝。
• 使用 formatNational() 格式化显示号码（如 5X XXX XXXX）。

国籍字段

• 仅列出 nationality.nationality_en 不为 null 的行（国家，以及台湾、香港和澳门）。
• 阿拉伯语中使用与个人性别相符的形式：nationality_ar_m（سعودي）或 nationality_ar_f（سعودية）。

数据

• null（或空列表）表示未知。应显示为未知；绝不要从其他来源补全。
• 仅加载所需模块；这些模块通过 iso2 关联。
• 固定版本（#v1.1.2、@1.1.2），避免名称和规则发生变化。

数据政策

• 此数据集不包含以任何名称或代码表示的以色列，任何文件中都没有。每次输出都会由测试强制检查这一点。
• 巴勒斯坦为「فلسطين」/“Palestine”，是一个国家，首都为「القدس」/“Jerusalem”。此处 +970 和 +972 的号码（包括耶路撒冷和 1948 年地区的线路）均为巴勒斯坦号码。其货币为约旦第纳尔和谢克尔（显示为「شيكل」/“Shekel”）。
• **有争议地区遵循沙特阿拉伯的官方立场：**西撒哈拉属于摩洛哥（不单独列项），包含科索沃，不包含北塞浦路斯；台湾、香港和澳门为拥有国籍的领土（它们签发自己的护照）。
• 对此政策的修改请求将直接关闭，不予讨论。欢迎提供带来源链接的数据更正（请参阅 CONTRIBUTING）。

字段

单语言构建会移除 _ar / _en 后缀（name_ar 在 .ar.json 中会变为 name）。

字段	模块	示例（SA）	含义
iso2	all	SA	ISO 3166-1 alpha-2 代码（科索沃为 XK）。用于关联所有模块的键。
iso3	core	SAU	ISO 3166-1 alpha-3 代码（按照 CLDR，科索沃为 XKK）。
iso_numeric	core	682	ISO 3166-1 数字代码，以文本形式保存以保留前导零。
kind	core	country	国家（主权国家，包括巴勒斯坦、梵蒂冈和科索沃）或地区。
name_ar	core	السعودية	阿拉伯语常用简称。
name_en	core	Saudi Arabia	英语常用简称。
official_name_ar	core	المملكة العربية السعودية	来源中有记载时提供的阿拉伯语官方全称。
official_name_en	core	Kingdom of Saudi Arabia	来源中有记载时提供的英语官方全称。
aliases_ar	core	["المملكة العربية السعودية","المملكة"...	人们搜索时使用的其他阿拉伯语名称。仅用于搜索，不用于显示。
aliases_en	core	["KSA","Kingdom of Saudi Arabia","Sau...	人们搜索时使用的其他英语名称。仅用于搜索，不用于显示。
flag	core	🇸🇦	国旗表情符号（区域指示符对）。Windows 无法绘制这些表情符号；在网页上请使用 flag_svg。
flag_svg	core	flags/sa.svg	此软件包中 4:3 SVG 国旗的路径。
continent	core	asia	africa、americas、asia、europe 或 oceania（通过 CLDR 获取的联合国 M49 数据）。
groups	core	["gcc","arab_league"]	所属组织：gcc、arab_league。
un_member	core	true	193 个联合国会员国的值为 true。
tld	core	.sa	已委派时提供的国家/地区代码顶级域名。
sort_ar	core	سعوديه	阿拉伯语排序键：使用普通字符串比较即可获得正确的阿拉伯语顺序（忽略「ال」、hamza 形式和 tashkeel）。
sort_en	core	saudi arabia	英语排序键：使用普通字符串比较即可。
nationality	nationality		国籍名称。国家以及 TW、HK、MO 有值；其他地区为 null。
nationality.nationality_ar_m	nationality	سعودي	阿拉伯语国籍称谓，阳性（سعودي）。
nationality.nationality_ar_f	nationality	سعودية	阿拉伯语国籍称谓，阴性（سعودية）。
nationality.nationality_en	nationality	Saudi	英语国籍形容词（Saudi）。
nationality.icao_code	nationality	SAU	护照上使用的 ICAO Doc 9303 代码（通常与 iso3 相同；德国为 D，科索沃为 RKS）。
phone	phone	[{"calling_code":"+966","leading_digi...	此行对应的编号计划。大多数行只有一个；部分行有多个（巴勒斯坦：+970 和 +972）。
phone[].calling_code	phone	+966	带 + 的国际电话区号。
phone[].leading_digits	phone	null	当多个国家/地区共用区号时，国家号码必须以此正则表达式匹配的数字开头（例如，多米尼加共和国的 +1 809|829|849）。若区号没有以这种方式共用，则为 null。
phone[].primary	phone	true	当此行对应区号的默认国家/地区时，值为 true。
phone[].trunk_prefix	phone	0	拨打国际区号前需从本地号码中去掉的数字（如 0501234567 中的 0）。
phone[].pattern	phone	(?:[15]\d|800|92)\d{7}	任何有效国家号码（所有类型）的正则表达式。需与完整国家号码匹配。
phone[].lengths	phone	[9,10]	有效国家号码的长度，涵盖所有类型。
phone[].mobile_pattern	phone	579[0-8]\d{5}|5(?:[013-689]\d|7[0-8])...	有效手机国家号码的正则表达式。需与完整国家号码匹配。
phone[].mobile_lengths	phone	[9]	有效手机国家号码的长度。
phone[].mobile_prefixes	phone	["50","51","53","54","55","56","57","...	手机号码的前导数字（最多 3 位）。用于快速检查；精确验证请使用 mobile_pattern。
phone[].mobile_distinguishable	phone	true	当手机号码和固定电话号码看起来相同时为 false（美国、加拿大）。
phone[].mobile_example	phone	512345678	手机国家号码示例，可用作输入占位符。
phone[].mobile_format	phone	## ### ####	手机国家号码的显示分组格式，# 表示数字。
currencies	currency	[{"code":"SAR","name_ar":"ريال سعودي"...	使用中的货币。
currencies[].code	currency	SAR	ISO 4217 代码。
currencies[].name_ar	currency	ريال سعودي	阿拉伯语货币名称。
currencies[].name_en	currency	Saudi Riyal	英语货币名称。
currencies[].symbol	currency	⃁	货币符号（存在时使用新的 Unicode 符号，例如里亚尔符号）。
currencies[].symbol_ar	currency	ر.س.	阿拉伯语书写的货币符号（ر.س）。
currencies[].symbol_fallback	currency	ر.س	字体不支持新符号时显示的文本。
geo	geo		地理信息。
geo.capital_ar	geo	الرياض	阿拉伯语首都名称。
geo.capital_en	geo	Riyadh	英语首都名称。
geo.lat	geo	23.7167	国家中心点的纬度。
geo.lng	geo	44.1167	国家中心点的经度。
geo.area_km2	geo	2149690	面积，单位为平方公里。
geo.population	geo	36973555	人口。
geo.population_year	geo	2025	人口数据的年份。
geo.timezones	geo	["Asia/Riyadh"]	IANA 时区名称。
geo.driving_side	geo	right	left 或 right。
locale	locale		区域惯例。
locale.languages	locale	[{"code":"ar","name_ar":"العربية","na...	官方语言，按使用人数从多到少排列。
locale.languages[].code	locale	ar	BCP 47 语言代码。
locale.languages[].name_ar	locale	العربية	阿拉伯语语言名称。
locale.languages[].name_en	locale	Arabic	英语语言名称。
locale.week_start	locale	sun	一周的第一天（sun、mon、sat 等）。
locale.weekend	locale	["fri","sat"]	周末日期。
locale.calendars	locale	["gregorian","islamic-umalqura","isla...	使用中的历法，按首选程度从高到低排列（gregorian、islamic-umalqura 等）。
locale.measurement	locale	metric	metric、us 或 uk。
address	address		邮政地址惯例。
address.postal_code_format	address	#####	邮政编码格式：# 表示数字，@ 表示字母。
address.postal_code_regex	address	^(?:\d{5})$	有效邮政编码的正则表达式。
address.postal_code_example	address	11564	邮政编码示例。
address.address_format	address	%N%n%O%n%A%n%C %Z	地址模板：%N 姓名，%O 组织，%A 街道，%D 区，%C 城市，%S 地区，%Z 邮政编码，%X 排序码，%n 换行。
address.region_label_ar	address	null	阿拉伯语中顶级地区的称谓。
address.region_label_en	address	null	顶级地区的称谓（州、省、酋长国等）。
travel	travel		旅行信息。
travel.emergency	travel		经官方来源确认的紧急电话号码。服务项为 null 时，请拨打 general。
travel.emergency.police	travel	999	警察。
travel.emergency.ambulance	travel	997	救护车。
travel.emergency.fire	travel	998	消防和民防。
travel.emergency.general	travel	911	全部服务通用号码（112、911、999 等）。
travel.plug_types	travel	["G"]	IEC 插头字母类型（A 至 N）。
travel.voltage	travel	[220,230]	住宅市电电压。
travel.frequency_hz	travel	[60]	市电频率，单位为赫兹。
sports	sports		体育代码。
sports.fifa	sports	KSA	FIFA 国家代码。
sports.ioc	sports	KSA	IOC 国家代码。
subdivisions.iso2	subdivisions	SA	国家/地区代码。
subdivisions.code	subdivisions	SA-01	ISO 3166-2 代码（SA-01）。
subdivisions.name_ar	subdivisions	منطقة الرياض	阿拉伯语名称。
subdivisions.name_en	subdivisions	Riyadh	英语名称。
subdivisions.parent	subdivisions	null	父级行政区划的 ISO 3166-2 代码，用于嵌套行政区划。

常见问题

如何获取阿拉伯语国家列表？ 使用 data/worldref.ar.json（如果只需要名称，则使用 data/modules/core.ar.json）。每一行都有阿拉伯语的 name。如需现成的选择器排序顺序，请按 sort 排序（排序时会忽略「ال」和各种形式的 hamza）。

在哪里可以找到阿拉伯语的男性和女性国籍名称列表？ data/modules/nationality.json：nationality_ar_m（سعودي）和 nationality_ar_f（سعودية），以及 nationality_en（Saudi）。

如何验证沙特阿拉伯手机号码？ 使用 parsePhone(input, byIso2("SA"))，并检查 valid && mobile。规则位于 phone[0].mobile_pattern：去掉开头的 0 后，为以 50、51、53 至 59 开头的 9 位数字。支持阿拉伯数字。

为什么有些国家的 travel.emergency.police 为 null？ 仅发布经官方来源确认的号码。如果某项服务为 null，请拨打 general。

可以将其用于商业用途吗？ 可以。代码采用 MIT 许可证；数据许可证（Unicode、Apache-2.0、CC-BY-4.0、CC0、公有领域）均允许商业使用，并在要求时注明出处。请参阅 LICENSE。

数据有多新？ 自动任务每月检查上游来源（人口数据每季度检查一次），在来源发生变化且所有测试通过时发布补丁版本。版本信息见 data/meta.json。

面向 AI Agent

请从 llms.txt 和 AGENTS.md 开始。架构定义位于 schema/。MCP 服务（npx -y worldref mcp）提供 get_country、search_countries、validate_phone 和 list_subdivisions。仅依据数据作答，并将 null 视为未知。

路线图

计划在 1.2.0 版本中推出（新增且不破坏兼容性）：

1. 官方阿拉伯语名称：目前有 222 行为空，这是数据中最大的缺口。
2. 提供两种语言的行政区划类型（地区、省、酋长国、州）。
3. 更宽容的搜索：支持不带标点或有少量拼写错误的名称（“cote divoire”、“Kuwiat”）。
4. 地址表单辅助工具：以阿拉伯语或英语提供某个国家地址表单的字段、顺序和标签。
5. 在 Maven Central 上提供 Kotlin，同时继续支持 JitPack。
6. 城市：新增 cities 模块，包含阿拉伯语和英语名称，并关联到对应的国家和行政区划。

来源和许可证

代码：MIT。数据：Unicode CLDR 49（Unicode-3.0）、Google libphonenumber v9.0.42 和地址元数据（Apache-2.0，已修改）、World Bank（CC-BY-4.0）、Wikidata（CC0）、CIA World Factbook 最终版和 IANA（公有领域）、flag-icons（MIT），以及用于紧急号码的官方政府来源。完整文本见：LICENSES/。各列来源和每项编辑决策见：data/sources.json。

引用方式：请参阅 CITATION.cff。