Skip to main content

AkariBot-I18N

小可使用的本地化组件。

运行时存储

load_locale_file() 会把 JSON 语言文件编译为版本化 SQLite 快照。多个进程使用同一组语言目录时会共享快照文件,并在其他进程发布新版本后自动刷新只读连接。

快照默认保存在当前用户的临时目录。可通过 AKARI_BOT_I18N_CACHE_DIR 指定本机缓存目录;所有 worker 必须使用相同配置。Locale.data 和模块级 locale_data 现在是只读映射。

加载和使用也可以完全分离。只有 loader 需要访问 JSON:

build_locale_snapshot(["zh_cn", "en_us"], locale_paths, "akari-bot")

其他 worker 只连接同一命名空间,不需要调用 load_locale_file() 或访问语言目录:

connect_locale_snapshot("akari-bot")

命名空间连接会自动跟随 loader 后续发布的新 generation。reader 调用 Locale.reload() 时也只会强制重连 manifest,不会读取 JSON。原有 load_locale_file() 保留为“构建并连接”的兼容入口。

每个 namespace 默认只保留当前和上一个 generation。更老的数据库会在 build 或 reader 完成版本切换时清理;Windows 上仍被其他进程打开的文件会在后续操作中重试删除。

术语占位符

同一句文案里的名词可能需要按平台与会话类型换称呼(QQ 群聊 → 「群聊」、Discord 频道 → 「频道」、私聊 → 「私聊」)。术语与变体都是普通词条,命名空间固定为 term.:

{
  "term.target": "场景",
  "term.target.private": "私聊",
  "term.target.discord": "频道",
  "term.target.qq.group": "群聊",
  "core.help.bind.channel": "查看当前{TERM:target}的消息通道:${channel} 号"
}

文案作者只写 {TERM:<name>},不接触变体键名。占位符可携带参数,参数只用于向术语文本插值(${...} 缺参数时原样保留),不参与变体选择:

{ "weekly.message.summary": "{TERM:target,count=${count}} 本周共有 ${count} 条动态。" }

标签必须大写、名称必须小写({term:x}、{TERM: Name} 一律按普通文本保留);{TERM:...} 与 {I18N:...} 互不干扰。不提供转义序列,{{TERM:x}} 不会被解析。

术语变体由调用方提供的候选链决定,组件不感知任何平台概念:

from akari_bot_i18n.i18n import Locale, derive_term_candidates

candidates = derive_term_candidates(("discord", "dm", "channel"), shared=("private",))
# -> ("discord.dm.channel", "discord.dm", "private", "discord")

locale = Locale("zh_cn", term_candidates=candidates)
locale.t("core.help.bind.channel", channel=3)  # -> 查看当前私聊的消息通道:3 号

语义是固定的:

  • 依次尝试 term.<name>.<candidate>,全部未命中则取基础键 term.<name>。
  • 变体只在 Locale 自身的语言中查找,不进入 fallback_lng,避免把中文名词嵌进英文句子;基础键走正常的本语言 → 回退链语义。
  • term_candidates=None(默认)表示未绑定会话作用域,() 表示已绑定但没有候选;两者都解析为基础术语。可用只读的 term_scoped 断言会话渲染用的对象确实绑定了作用域。
  • 术语在所有语言中都不存在时原样保留占位符(含参数),不附加回退提示,便于直接看到缺失的术语名。

Locale 的新增接口:

接口 说明
Locale(locale, fallback_lng=None, *, term_candidates=None) 构造时绑定候选链
with_locale(tag) / with_term_candidates(cands) 派生副本,保留作用域与其他设置;换语言时回退链里的自指项会换成派生前的语言
term(name, **params) / term_key(name) 解析单个术语 / 返回命中的键(诊断);term("target") 与 term(name="target") 都可用,且 name= 仍可作为占位符参数名
term_candidates / term_scoped 只读候选链与作用域标记
to_state() / Locale.from_state(state) 跨进程/RPC 传递状态;字段只增不改,容忍缺字段与未知字段

术语在 t()(含 dict 分支)与 t_str() 中解析,因此所有渲染路径自动生效;strftime 的格式串、__getitem__ / __contains__ / data 不解析术语。

术语校验

build_locale_snapshot() 与 load_locale_file() 默认开启术语校验(audit_terms=False 可关闭),把问题追加到既有的 errors 列表:被引用但基础键缺失、占位符写法可疑、术语值含占位符、有变体无基础键。与跨文件键冲突同级别:报告但不阻断快照发布,has_load_failures 不置位。也可单独调用:

from akari_bot_i18n.i18n import audit_terms

audit_terms()                              # 当前快照的全部语言
audit_terms(["zh_cn"])                     # 指定语言
audit_terms(include_unreferenced=True)     # 附带「基础术语从未被引用」的信息级条目

Metadata

Release files for akari-bot-i18n 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for akari-bot-i18n 0.2.0
File Size Uploaded Provenance Actions
akari_bot_i18n-0.2.0.tar.gz 37.4 kB With provenance Details for akari_bot_i18n-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for akari-bot-i18n 0.2.0
File Interpreter ABI Platform Actions
akari_bot_i18n-0.2.0-py3-none-any.whl Python 3 none any Details for akari_bot_i18n-0.2.0-py3-none-any.whl

Total release size: 75.2 kB

Release files / akari_bot_i18n-0.2.0.tar.gz

Download URL akari_bot_i18n-0.2.0.tar.gz
Size 37.4 kB
Tags Source
SHA-256 checksum
How to use checksums
fb93d8a3f0019e3cd95c9164e2b156ddba5f57768e28c535734da65b51bcebef
BLAKE2b-256 checksum
How to use checksums
e9811391827f39e04927431066a0e6d6e693634db4dd5107ef86786f2c55bf42
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.

Transparency log

Release files / akari_bot_i18n-0.2.0-py3-none-any.whl

Download URL akari_bot_i18n-0.2.0-py3-none-any.whl
Size 37.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f2d83dbf8fb3ff45e0f4024eaf4fef2ef38c8b3a445927b02b2a2547273dcb5f
BLAKE2b-256 checksum
How to use checksums
d241c8b7cfedfa4c25a91d8fa8f446cd5f2a9ca9dc08db4d11d113ff9877f4f9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.

Transparency log

Security for akari-bot-i18n 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for akari_bot_i18n-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page