跳转至

运行时错误消息国际化

运行时错误消息国际化

pyrs-yaml 支持错误消息的运行时国际化。错误消息可以显示为英语、简体中文（zh-CN）、日语（ja-JP）和韩语（ko-KR）。

如需站级文档国际化（MkDocs），请参阅站级国际化。

可用函数

set_language()

设置错误消息的语言。

函数签名
set_language(lang: str) -> None

支持的语言： "en", "zh-CN", "ja-JP", "ko-KR"

get_language()

获取当前错误消息语言。

函数签名
get_language() -> str

list_languages()

列出所有支持的语言。

函数签名
list_languages() -> list[str]

detect_language()

从环境变量自动检测用户的首选语言。

函数签名
detect_language() -> str

按顺序检查 LANG、LC_MESSAGES 和 LC_ALL 环境变量。

negotiate_language()

BCP 47 语言协商 — 从支持的语言中返回最佳匹配。

函数签名
negotiate_language(user_locales: list[str], default: str = "en") -> str

示例

切换错误消息语言
import pyrs_yaml

# 切换到中文错误消息
pyrs_yaml.set_language("zh-CN")

try:
    pyrs_yaml.parse("invalid: yaml: [")
except pyrs_yaml.YamlParseError as e:
    print(e)
    # "YAML 解析错误: 第 1 行, 第 14 列: ..."

# 从 LANG 环境变量自动检测
lang = pyrs_yaml.detect_language()
print(lang)  # 例如 LANG=zh_CN.UTF-8 时返回 "zh-CN"

# BCP 47 协商
best = pyrs_yaml.negotiate_language(["zh-Hans", "en"])
print(best)  # "zh-CN"

支持的语言

代码 语言 示例
en English "YAML parse error: line 1, column 14: ..."
zh-CN 简体中文 "YAML 解析错误: 第 1 行, 第 14 列: ..."
ja-JP 日语 "YAML 解析エラー: 1 行目, 14 列目: ..."
ko-KR 韩语 "YAML 구문 분석 오류: 1번째 줄, 14번째 열: ..."

支持国际化的错误类型

所有公共错误类型都支持国际化：

  • YamlParseError — 解析失败
  • YamlSerializeError — 序列化失败
  • YamlTypeError — 类型转换错误
  • YamlValidateError — JSON Schema 验证错误
  • YamlEditError — 编辑失败
  • YamlPathError — 格式错误的编辑路径错误
  • YamlDuplicateKeyError — 重复键检测
  • YamlMaxDepthError — 超出嵌套深度

最佳实践

启动时配置一次 i18n
import os
import pyrs_yaml


def setup_i18n():
    """Configure i18n from environment or user preference."""
    lang = pyrs_yaml.detect_language()
    pyrs_yaml.set_language(lang)
    return lang

另请参阅