ISO 639-1语言代码实战：查询、校验、存储与避坑指南

简介ISO 639-1 语言代码列表是面向 Go 开发者的一站式语言编码查阅包主要解决多语言应用开发中快速获取语言名称、当地名称及两字母代码的常见问题适用于国际化i18n场景、语言选择器、表单校验和本地化数据处理等模块。资源包共 10 个文件以 Go 源码为主体5 个 .go涵盖入口逻辑、语言列表数据及单元测试另有 2 个 Markdown 文档分别提供使用说明与贡献指南并附开源许可和 CircleCI 配置压缩包整体仅 9KB轻量、无第三方依赖可直接集成到项目使用目前已有 930 人学习浏览。包内通过 Codes、Names、NativeNames、Languages 四个公开集合把全部 ISO 639-1 双字母代码、英文名称与本地名称统一暴露出来并在 init 函数中完成预加载确保运行时读取迅速免去自行维护语言清单的繁琐。测试文件覆盖列表完整性与常见查询场景源码文件按功能拆分清晰便于阅读和二次扩展同时附带许可与多个文档方便团队内部快速评估合规性。对于需要在国际化和本地化功能中引入标准语言枚举的 Go 工程师来说是一个可直接上手、结构紧凑的参考实现。1. 语言选择器里存了中文联调时谁都认不出谁做多语言系统的第一天最容易踩的坑不是翻译文件而是语言标识本身。A同学的前端把用户选择的语言直接存成中文后端接口规范里写的是zh-CN另一个老系统用的是cn三个值在数据库里一碰谁都不认识谁。更隐蔽的是产品经理过来说要加粤语开发随手填了个yue结果老系统直接拒绝因为它只认ISO 639-1的两字母代码。ISO 639-1就是解决这个问题的标准答案它为全球主要语言分配了唯一的、稳定的两字母代码比如en代表英语、zh代表汉语、de代表德语。它不是给语言做排名而是一张词典让前端、后端、数据库、第三方服务在说这门语言的时候用的是同一个值。这篇文章会把这套代码表的边界讲清楚然后给出查询、校验、存储和迁移的完整落地路径。适合正在做国际化、内容多语言归档、或者要接第三方翻译服务的开发者。2. ISO 639-1是什么两字母代码的边界、来源与选型2.1 一个代码对应一种语言但代码总量有限ISO 639-1的结构很简单两个小写英文字母一个是语言代码比如ja是日语、fr是法语。因为只有26个字母两两组合上限是676个实际在册的只有180多个。这个少不是缺点反而是它的设计目标只覆盖全球使用人数较多、有书面文字系统的主要语言保证两字母代码好认、好记、够用。同一个语言内部存在地域变体时ISO 639-1层面不做细分zh就是汉语无论简体还是繁体在代码层面都是zh。真正区分简繁体要靠ISO 15924文字代码里的Hans和Hant写成zh-Hans、zh-Hant。还有一种情况是宏观语言概念一个代码对应一组相近的语言或方言。中文的zh就是典型的宏观语言涵盖官话、粤语、吴语等挪威语的no同样如此它下面还有两个独立的两字母代码这个坑后面专门讲。代码包含两类特殊状态一类是退役代码比如希伯来语从iw改成he、意第绪语从ji改成yi、印尼语从in改成id这些旧代码在标准里做了弃用标记但现实中老系统里到处都是另一类是保留代码留给未来可能新增的语言不分配给任何现有语言。这两类状态在实际开发中都要处理不然会出现合法代码查不到语言的诡异问题。2.2 639-1、639-2、639-3该用哪一套ISO 639家族不止一张表最常见的还有639-2和639-3。很多开发者在选型时会纠结其实按场景走就行不需要全上。从定位上看三套标准的区别主要在于覆盖范围和代码长度。标准代码长度覆盖数量级典型用途ISO 639-12位字母180多种主要语言用户界面语言、HTTP头、数据库通用字段ISO 639-23位字母约490种语言文献编目、图书馆系统、历史资料归档ISO 639-33位字母超过7000种语言语言学、语料库标注、少数民族语言研究639-2还有一个特殊的双编码体系分为术语学编码T码和书目学编码B码例如德语在T码下写gerB码下写deu虽然两者现在可以通用但刚接触时容易看懵。639-3则是面向语言学的穷举式清单代码和639-2部分重合覆盖范围大得多是NLP语料标注的首选。我的选择原则是面向终端用户的产品语言一律用639-1它短、输入友好、生态支持最全做文献管理或者处理历史数据用639-2做语音识别或翻译模型的训练语料标注上639-3。最忌讳的是混用系统里既出现zh又出现zho校验逻辑直接翻倍。如果只是做网站国际化和接口设计锁定639-1就够了。2.3 语言代码与localelang和locale不是一回事ISO 639-1只回答哪门语言的问题但现代软件通常还需要知道哪个地区的人在说这门语言这就引出了locale概念。locale一般写作语言-地区的形式比如en-US表示美国英语en-GB表示英式英语。这里的US和GB是ISO 3166-1的地区代码属于另一套标准但人们习惯把它们组合使用。完整的组合语法遵循BCP 47规范顺序是语言-文字-地区例如zh-Hans-CN表示中国大陆使用的简体中文zh-Hant表示繁体中文。注意语言代码必须小写地区代码必须大写文字代码首字母大写。这套规范被HTTP的Accept-Language头、浏览器navigator.language属性、HTML的lang属性直接引用是所有现代Web语言识别的基础。搞清楚这个区分非常重要因为ISO 639-1本身不解决简体和繁体选哪个的问题也不解决巴西葡萄牙语和欧洲葡萄牙语文案不同的问题。前者要靠加文字代码后者要靠加地区代码。如果只存一个zh就指望系统自动判断用户该看简体还是繁体那是把标准用错了地方。所以国际化的数据模型里语言和locale应该是两个字段而不是混成一列。3. 把ISO 639-1落到系统里查询、校验、存储3.1 用Python查出一门语言的代码和名称最常见的需求是把用户选择的语言名称或代码互相转换。Python生态里有现成工具不必自己维护一张语言列表。pycountry这个库把ISO 639全系列代码封装成了对象按alpha_2字段就能拿到ISO 639-1的代码。import pycountry # 通过ISO 639-1代码查语言对象 lang pycountry.languages.get(alpha_2zh) print(lang.name) # 输出 Chinese # 反查用语言名称找代码注意zh的name就是Chinese for item in pycountry.languages: if item.name and item.name.lower() chinese: print(item.alpha_2, item.alpha_3)这门语言的alpha_2返回zhalpha_3返回zho。如果某种语言只有三字母代码alpha_2字段会是None比如粤语的alpha_3是yue但在639-1里没有它的位置。pycountry覆盖很全但注意它是不区分在册和废弃代码的直接遍历时可能会碰到名字都为None的弃用条目需要自己过滤。另一个常用库是langcodes它更贴近BCP 47的tag解析。如果要做的是接收用户输入的语言标签比如zh-Hant-TW或者pt-BR再用langcodes解析成标准形式会更顺手。pycountry和langcodes的分工建议是pycountry负责查语言基础信息langcodes负责解析和规范化复杂的语言标签。3.2 前端lang属性与HTTP消息头里的标准用法前端接触ISO 639-1最频繁的地方是HTML的lang属性和HTTP的Accept-Language头。不要小看这两个位置它们直接影响浏览器翻译、屏幕阅读器发音和网页的SEO语义。声明页面主语言最标准的写法是在html标签上指定lang属性。html langzh-CN这段代码告诉浏览器页面正文被识别为中国大陆使用的简体中文这个locale。如果你的页面是多语言混合的每个区块都可以覆盖这个声明比如在包含英文引文的区块上写span langen。样式表里也可以用:lang()选择器针对不同语言做排版微调比如日文截断、阿拉伯文字体。HTTP层面则是服务器响应头或者请求头里做语言协商Accept-Language: zh-CN,zh;q0.9,en;q0.8这里的q是权重参数0.9和0.8表示优先级的数值数字越大优先级越高。中间件解析这个头之后再配合后端维护的语言代码表就能给用户返回对应语言的界面文案。前端用JavaScript读取浏览器语言时navigator.language返回的值格式也是BCP 47风格例如zh-CN拿到后需要拆包处理不要直接拿整个字符串去跟ISO 639-1比对。3.3 数据库字段设计存代码而不是存名称数据库里存中文还是存zh这个问题很多团队在项目中期才意识到重要性。存中文名称的代价非常大不同系统对同一门语言的叫法不一致中文汉语简体中文都可能是同一个意思一旦产品要出海数据库里还要再存一份英文名称更麻烦的是名称会跟着业务翻译走而代码是稳定的。所以主语言字段应当存代码。字段名示例值长度说明language_codezhchar(2)ISO 639-1代码必填localezh-Hansvarchar(12)BCP 47标签可选存完整的语言变体script_codeHanschar(4)ISO 15924文字代码可选region_codeCNchar(2)ISO 3166-1地区代码可选语言代码统一存小写地区代码统一存大写这是业界通用约定。表结构上如果产品必须区分简繁体建议在独立字段存lang和locale两个值而不是把zh-Hans整个塞进一个字段再靠程序去拆。查询时按locale字段建索引配合接口层解析比硬解析字符串快得多也不会在用户传zh-HANS或ZH-CN时翻车。4. 避坑指南语言代码最容易翻车的五个现场4.1 把cn当中文它不是ISO 639-1代码现象接口文档里写着languagecn前端传参正常后端发现语言代码校验不通过数据库里中文记录全部匹配失败。原因很多人想当然地认为cn是中国的英文缩写就直接拿来当中文代码。实际上cn在ISO 639-1里根本不存在它是ISO 3166-1中的中国地区代码。中文在两字母标准里一直是zh没有其它选择。解决代码审查时加一条硬性规则——语言代码必须从白名单里选白名单以ISO 639-1为准接收外部数据时如果遇到cn或ch不能直接给换成zh要记录异常日志并让上游系统改成标准值因为历史数据里还可能混入更乱的写法。4.2 希伯来语传iw返回错误旧代码退役现象老项目数据库里存了一堆iw新系统用的语言代码校验工具不认而这些数据在旧系统里一直显示正常。原因希伯来语在ISO 639-1早期版本中的代码就是iw后来标准更新把代码改成了he。同样退役的还有意第绪语ji改成yi、印尼语in改成id。很多老系统用的还是十多年前的数据字典。解决不要强制新系统去兼容旧代码而是写一个显式的映射关系在数据接入层把iw、ji、in转成标准代码。这个映射关系写进配置文件而不是散落在业务代码里后续升级标准时可以一键切换。如果用的是pycountry要注意它可能把废弃代码和现行代码同时列出必须自己判断。4.3 粤语在ISO 639-1里根本没有位置现象产品经理要求增加粤语界面开发在语言表里加了一行yue结果前端下拉框显示正常但所有依赖ISO 639-1代码的服务都把这个值拒了。原因yue是国际标准中粤语的代码但它是ISO 639-3的三字母代码在639-1的180多个代码里没有粤语。两字母标准只收录宏观语言zh不细分到粤语、吴语这个层级。解决如果产品只需要让粤语用户能看懂界面通常是用zh-HK这个locale来近似表达借助地区来隐式区分如果业务真的要求标准层面把粤语独立出来那整条语言链路必须升级到支持639-3前端、后端、数据库、第三方翻译服务要一起改造不是加一行数据能解决的。4.4 大小写混用导致匹配失败现象数据库中查到的语言代码是大写EN代码里写equals(en)永远为false排查半天发现用例都是小写。原因ISO 639-1规定代码必须小写ISO 3166-1规定地区代码必须大写。但实际生产里上游系统经常把两者混在一起传过来EN-us或者zh-cn这种非标准写法。解决在接口入口统一做规范化处理不要信任任何上游。语言部分强制lower地区部分强制upper文字部分首字母大写。这一步在每个服务的入口处做不要在数据库里反复用upper函数来救火数据落库前就应该是标准形态。4.5 挪威语的no、nb、nn是一个三角关系现象用户选了挪威语系统存了no但查看语言统计报表时发现no的点击量是0而nb和nn各有数据业务方怀疑数据丢了。原因挪威语在ISO 639-1里不是单一代码。no是宏观语言代码nb是书面挪威语更常用nn是新挪威语。用户实际上选的界面语言是书面挪威语代码应该是nb但很多通用接口默认返回no。解决业务系统里如果出现挪威语优先使用nb或nn把no作为宏观兜底值仅用于无法区分具体挪威语变体的情况。前端语言下拉框不要把no和nb同时展示给用户否则没人知道该选哪个。ISO数据是标准的但产品交互需要自己做好包装。5. 进阶做法自建语言代码注册表5.1 用一张表做全公司的语言字典依赖第三方库直接查语言信息虽然方便但有一个隐患库的更新节奏由上游维护者决定团队无法控制。而且业务上需要展示这门语言在界面里叫什么不同部门可能想要不同的展示文案。更稳妥的做法是在业务系统里维护一张属于自己的语言注册表作为唯一真实数据源。CREATE TABLE language_registry ( alpha_2 CHAR(2) PRIMARY KEY, alpha_3 CHAR(3) NOT NULL, english_name VARCHAR(64) NOT NULL, native_name VARCHAR(64) NOT NULL, locale_example VARCHAR(16), deprecated BOOLEAN DEFAULT FALSE, replacement CHAR(2), updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP );这张表的关键字段是alpha_2、alpha_3、native_name和deprecated。english_name给开发看native_name给界面下拉框用deprecated标记退役代码replacement指向新代码。建议把ISO 639-1的全部在册代码初始化进去初始化的数据来源用第三章提到的pycountry导出一次生成SQL脚本入库后续不再从库动态查询。这张注册表的价值在于它是公司内部所有系统的语言代码字典前端下拉框、后端校验、数据仓库维度表、翻译供应商映射都从这里取值。不要每次需要语言列表时都去调外部接口离线表在任何环境下都是最快的。5.2 兼容历史脏数据写一个清洗函数有了注册表之后还需要一道防线来处理历史脏数据和上游乱传的代码。清洗函数的核心逻辑是先转小写再查废弃映射表最后交给白名单校验。这三步缺一不可尤其不要跳过废弃映射直接做白名单校验。LEGACY_MAP { iw: he, ji: yi, in: id, mo: ro, } VALID_CODES {zh, en, de, fr, ja, ...} def normalize_language_code(raw_code): if not raw_code or not isinstance(raw_code, str): return None code raw_code.strip().lower() if code in LEGACY_MAP: return LEGACY_MAP[code] return code if code in VALID_CODES else None这个清洗函数放在所有语言数据流入业务表之前统一在服务入口层调用。收到iw会返回he收到cn会返回None要求上游修正而不会静默地臆测它是什么语言。注意清洗函数只做代码映射不做语义推断拿不准的宁可直接拒绝也不要乱猜。日常维护中真正麻烦的不是标准代码而是半标准代码比如把中文简体和地区码拼成zh-CN的标签带横杠的完整locale不应该直接进语言代码字段。遇到这种输入建议单独走BCP 47解析流程而不是在清洗函数里硬拆字符串因为变体的数量远超过你能枚举的范围。5.3 给语言代码做版本管理锁定而不是天天追新ISO 639-1不是恒定不变的偶尔会有代码退役、新增语言但频率不高。很多团队误以为标准更新就要立刻同步结果每次ISO公告出来都要发一次版本还容易引发存量数据不兼容。更好的做法是锁版本、定期评估、按需升级。在语言注册表里增加一个version字段记录这张表基于ISO标准的哪一次修订生成。业务代码不直接依赖ISO官网的实时状态而是依赖注册表里的白名单。当发现确有需求比如要支持一门新增的少数民族语言再专门指派一次升级跑完回归测试后发布。日常不需要追新。版本管理还有一个容易被忽略的层面语言展示名称会变。同一门语言在不同地区的称呼不一样产品上线后经常要调整某个名称此时只改注册表的native_name字段即可alpha_2主键不变所有关联数据都不受影响。这正是把语言名称和语言代码拆开管理的收益。6. 用自动化测试锁住语言代码质量别靠人眼校验语言代码这种看起来就几个字母的东西最容易被人忽略测试。真实项目里一个手误把zh写成了ha界面啥都显示不出来排查半小时最后发现是配置文件少了个字母。所以我习惯在代码仓库里放一个参数化的测试用例把语言白名单、清洗函数、接口响应三层全部覆盖。import pytest pytest.mark.parametrize(input,expected, [ (zh, zh), (ZH, zh), (iw, he), (cn, None), (, None), ]) def test_normalize_language_code(input, expected): assert normalize_language_code(input) expected pytest.mark.parametrize(code, [zh, en, de, fr, ja, nb, nn]) def test_all_active_codes_resolve(code): lang lookup_registry(code) assert lang is not None assert lang.deprecated is False第一组测试关注清洗函数的边界行为包括大小写、废弃映射和非法值第二组遍历当前注册表里的活跃代码确保每一个都能查到名称。这样每次有开发改动了语言映射配置CI一跑就能发现是否破坏了基础规则。还有一个我踩过的坑是只测合法值不测边界值。代码表相关的测试一定要覆盖空字符串、null、超出两位长度、数字混合几种输入不然清洗函数可能在毫不知情的情况下把123原样传下去。接口层的校验规则应该是拒绝而不是修正把不合法值挡在门外比产生一条错误数据更好处理。实践里我会再补一道实现细节前端下发语言代码时接口返回错误必须带清晰提示。用户选择语言是低频操作但它影响全站文案一旦出错所有页面都是乱码。把错误信息从invalid value改成缺少语言代码或代码不在ISO 639-1范围内请检查zh/en/de格式排障速度会快很多。语言代码这种东西平时不起眼出了事全是熬夜排查提前用自动化锁住算是我交过学费后最值回票价的一个习惯。希望帮到你。本文还有配套的精品资源点击获取