Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
name: CI

on:
push:
pull_request:

permissions:
contents: read

jobs:
test:
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
cache: pip
cache-dependency-path: |
unity-text-locator/requirements.txt
ainiee-translate/requirements.txt
- name: Install runtime dependencies
run: >-
python -m pip install
-r unity-text-locator/requirements.txt
-r ainiee-translate/requirements.txt
- name: Compile Python sources
run: python -m compileall -q unity-text-locator/scripts ainiee-translate/scripts
- name: Run regression tests
run: python -m unittest discover -s tests -v
- name: Smoke-test Unity command help
shell: python
run: |
import pathlib
import subprocess
import sys

scripts = sorted(pathlib.Path("unity-text-locator/scripts").glob("*.py"))
for script in scripts:
subprocess.run([sys.executable, str(script), "--help"], check=True, stdout=subprocess.DEVNULL)
print(f"validated {len(scripts)} command entry points")
9 changes: 6 additions & 3 deletions NOTICE
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ The detailed vendored notice is kept at:
Font assets
-----------

The `arialuni_sdf_u2019` TMP font asset is not committed to this repository.
If distributed, it should be attached separately as a GitHub Release asset and
its redistribution terms should be verified separately from this code license.
No third-party font binary is covered by this repository's AGPL-3.0 license.
`arialuni_sdf_u2019` must not be committed or published as a Release asset
unless the distributor has explicit redistribution rights for that derivative.
Noto-derived release packs may be distributed only with the applicable SIL
OFL 1.1 license, copyright/source records, modification disclosure, hashes,
and build metadata described in `docs/release-assets.md`.
11 changes: 9 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@

```powershell
$repo = "path\to\unity-text-locator"
$skills = Join-Path ($env:CODEX_HOME ?? (Join-Path $HOME ".codex")) "skills"
$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
$skills = Join-Path $codexHome "skills"
Copy-Item (Join-Path $repo "unity-text-locator") $skills -Recurse -Force
Copy-Item (Join-Path $repo "ainiee-translate") $skills -Recurse -Force
```
Expand All @@ -25,6 +26,12 @@ py -3.12 -m venv "$HOME\.venvs\ainiee-translate"
& "$HOME\.venvs\ainiee-translate\Scripts\python.exe" -m pip install -r "$repo\ainiee-translate\requirements.txt"
```

Unity 扫描、写回和字体检查还需要安装 Unity 运行依赖:

```powershell
py -3.12 -m pip install -r "$repo\unity-text-locator\requirements.txt"
```

## 工作流

```text
Expand Down Expand Up @@ -59,7 +66,7 @@ py -3.12 -m venv "$HOME\.venvs\ainiee-translate"
仓库不捆绑或指定默认字体二进制。字体必须由使用者合法取得,并针对目标游戏验证:

```powershell
python unity-text-locator\scripts\inspect_tmp_font_bundle.py path\to\font.bundle --translation-csv path\to\game_translation.csv
python unity-text-locator\scripts\inspect_tmp_font_bundle.py path\to\font.bundle --translation-root path\to\translation-output
```

检查结果应同时关注:
Expand Down
4 changes: 3 additions & 1 deletion ainiee-translate/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: ainiee-translate
description: Use when the user wants to translate a novel/epub end-to-end on the coding agent itself (Claude Code or Codex; no AiNiee app), AiNiee-style — parse, build a locked glossary, translate chapter by chapter following rules (names preserved, title 3-way, term consistency), write back and export. Triggers on "用 agent 翻译这本书", "agent 版 aniee 翻译", "把这本 epub 翻译了" and similar.
description: Translate books, documents, AiNiee projects, or Unity localization caches end-to-end on the coding agent itself without the AiNiee app. Use for requests such as "用 agent 翻译这本书", "把 epub 翻译了", "翻译 Unity CSV/cache", or "AiNiee-style translation" that need a locked glossary, resumable batches, terminology consistency, validated cache writeback, and export.
---

# ainiee-translate 技能指南
Expand All @@ -18,6 +18,8 @@ parse → 构建锁定词汇表 → 逐章翻译(agent 按规则) → 写回
- 进度状态驱动(`translation_status`):中断后重跑自动从首个未译段继续,天然可恢复。
- 每批写回前自动备份(时间戳):`cache.json.bak.YYYYMMDD_HHMMSS`。

完整性门禁:写回前要求 `text_index` 唯一,写入使用锁和原子替换;批次存在 unmatched、验证存在 issue、或 Unity cache 缺行/状态未完成时默认退出非零。只有用户明确接受保留未译行时才使用 `--allow-partial`。

本技能自带管道脚本(`scripts/ainiee_translate/`),无需单独 `pip install` 本包;解析/导出模块也随技能打包。跨设备复制后,只需要用本目录的 `requirements.txt` 为运行脚本的 Python 安装依赖。

---
Expand Down
4 changes: 4 additions & 0 deletions ainiee-translate/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
interface:
display_name: "AiNiee Agent Translation"
short_description: "Translate books and Unity text caches safely."
default_prompt: "Use $ainiee-translate to translate this book or Unity localization cache with a locked glossary, resumable batches, validation, and safe export."
16 changes: 8 additions & 8 deletions ainiee-translate/requirements.txt
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Runtime dependencies for ainiee-translate.
# Keep this in sync with upstream pyproject.toml dependencies.
msgspec
beautifulsoup4
lxml
rich
openpyxl
polib
python-pptx
chardet
msgspec>=0.18,<1
beautifulsoup4>=4.12,<5
lxml>=4.9,<7
rich>=13,<15
openpyxl>=3.1,<4
polib>=1.2,<2
python-pptx>=1.0,<2
chardet>=5,<6
4 changes: 3 additions & 1 deletion ainiee-translate/scripts/ainiee_translate/batch.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,11 @@ def main(argv=None):
applied = write_back(a.cache_path, translations)
if applied < total:
print(f"applied {applied} of {total} translation(s) ({total - applied} unmatched)")
return 1
else:
print(f"applied {applied} translation(s)")
return 0


if __name__ == "__main__":
main()
raise SystemExit(main())
88 changes: 78 additions & 10 deletions ainiee-translate/scripts/ainiee_translate/cache_io.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,12 @@
iterate / mutate items by translation status. The CacheProject / CacheItem types
are vendored from AiNiee under _vendor/ — no external AiNiee repo required."""
import json
import os
import tempfile
import time
import types
from contextlib import contextmanager
from pathlib import Path
import msgspec
from . import helpers
from ._vendor.ModuleFolders.Service.Cache.CacheProject import CacheProject, CacheProjectStatistics
Expand All @@ -20,8 +25,46 @@ def save_cache(project, path: str) -> None:
# Ensure stats_data is never null (its field type is non-Optional in msgspec eyes)
if project.stats_data is None:
project.stats_data = CacheProjectStatistics()
with open(path, "wb") as w:
w.write(msgspec.json.encode(project))
target = Path(path)
target.parent.mkdir(parents=True, exist_ok=True)
payload = msgspec.json.encode(project)
fd, tmp_name = tempfile.mkstemp(prefix=f".{target.name}.", suffix=".tmp", dir=target.parent)
try:
with os.fdopen(fd, "wb") as w:
w.write(payload)
w.flush()
os.fsync(w.fileno())
os.replace(tmp_name, target)
except BaseException:
try:
os.unlink(tmp_name)
except FileNotFoundError:
pass
raise


@contextmanager
def _cache_lock(cache_path: str, timeout: float = 10.0):
"""Portable cooperative lock using atomic O_EXCL creation."""
lock_path = f"{cache_path}.lock"
deadline = time.monotonic() + timeout
while True:
try:
fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
break
except FileExistsError:
if time.monotonic() >= deadline:
raise TimeoutError(f"cache is locked: {cache_path}")
time.sleep(0.05)
try:
with os.fdopen(fd, "w", encoding="ascii") as handle:
handle.write(str(os.getpid()))
yield
finally:
try:
os.unlink(lock_path)
except FileNotFoundError:
pass


def load_cache(path: str):
Expand Down Expand Up @@ -79,11 +122,36 @@ def set_polish(project, text_index: int, polished_text: str) -> bool:
def apply_writeback(cache_path: str, items: list[dict], setter, get_text) -> int:
"""Backup, load, apply `setter(project, text_index, get_text(item))` for each
item, save. Shared by the translate (batch) and polish write paths."""
helpers.backup_file(cache_path)
project = load_cache(cache_path)
applied = 0
for it in items:
if setter(project, int(it["text_index"]), get_text(it)):
applied += 1
save_cache(project, cache_path)
return applied
if not isinstance(items, list):
raise ValueError("writeback payload must be a JSON array")
indexes = []
for position, item in enumerate(items, start=1):
if not isinstance(item, dict) or "text_index" not in item:
raise ValueError(f"writeback item {position} has no text_index")
raw = item["text_index"]
if isinstance(raw, bool):
raise ValueError(f"invalid text_index at item {position}: {raw!r}")
try:
index = int(raw)
except (TypeError, ValueError) as exc:
raise ValueError(f"invalid text_index at item {position}: {raw!r}") from exc
if index <= 0 or str(raw).strip() != str(index):
raise ValueError(f"invalid text_index at item {position}: {raw!r}")
indexes.append(index)
if len(indexes) != len(set(indexes)):
raise ValueError("duplicate text_index in writeback payload")

with _cache_lock(cache_path):
project = load_cache(cache_path)
cache_indexes = [int(item.text_index) for item in iter_items(project)]
if len(cache_indexes) != len(set(cache_indexes)):
raise ValueError("cache contains duplicate text_index values")
applied = 0
for item, index in zip(items, indexes):
if setter(project, index, get_text(item)):
applied += 1
if applied != len(items):
return applied
helpers.backup_file(cache_path)
save_cache(project, cache_path)
return applied
8 changes: 5 additions & 3 deletions ainiee-translate/scripts/ainiee_translate/helpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,17 @@
ainiee-cache-fix skill (apostrophe normalization + Latin-only boundaries)."""
import re
import shutil
import time
from datetime import datetime, timezone
from uuid import uuid4

_APOS = {"'": "'", "ʼ": "'", "'": "'", "’": "'"}
_CJK = re.compile(r"[一-鿿]")


def backup_file(path: str) -> str:
"""Timestamped copy alongside the original: path.bak.YYYYMMDD_HHMMSS."""
dst = f"{path}.bak.{time.strftime('%Y%m%d_%H%M%S')}"
"""Create a collision-resistant backup alongside *path*."""
stamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S_%fZ")
dst = f"{path}.bak.{stamp}.{uuid4().hex[:8]}"
shutil.copy2(path, dst)
return dst

Expand Down
3 changes: 2 additions & 1 deletion ainiee-translate/scripts/ainiee_translate/verify.py
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,8 @@ def main(argv=None):
issues = check_items(_items_for_check(a.cache), locked)
print(json.dumps(issues, ensure_ascii=False, indent=2))
print(f"\n{len(issues)} issue(s)")
return 1 if issues else 0


if __name__ == "__main__":
main()
raise SystemExit(main())
30 changes: 17 additions & 13 deletions docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,13 @@ unity-text-locator/
如果需要全自动 Unity 翻译,请同时安装两个 skill 目录。
如果只需要半自动的提取、校验、写回流程,只安装 `unity-text-locator` 即可。

Unity 资源脚本依赖 Python 3.12 和 `UnityPy`:

```powershell
$repo = "path\to\unity-text-locator"
py -3.12 -m pip install -r "$repo\unity-text-locator\requirements.txt"
```

## 安装到 Codex

PowerShell:
Expand Down Expand Up @@ -43,22 +50,19 @@ $env:AINIEE_PY = "$env:USERPROFILE\.venvs\ainiee-translate\Scripts\python.exe"

`AINIEE_REPO` 是可选项,只在 vendored `ainiee-translate` reader 尚不支持某些格式时使用。

## 字体 Release 资产
## 字体

安装 `unity-text-locator` skill 后,把 release 里的 `arialuni_sdf_u2019` 下载到 skill 的 `assets` 目录:
不要从本仓库下载或发布 `arialuni_sdf_u2019`;Arial Unicode MS 及其 SDF 衍生资产需要单独、明确的再分发授权。

```powershell
$skillDir = "$env:USERPROFILE\.codex\skills\unity-text-locator"
New-Item -ItemType Directory "$skillDir\assets" -Force
Invoke-WebRequest `
"https://github.com/timeance/unity-text-locator/releases/latest/download/arialuni_sdf_u2019" `
-OutFile "$skillDir\assets\arialuni_sdf_u2019"
```

校验下载结果:
Mono/TMP 游戏优先使用自己合法取得的 Noto CJK/SC、TTF、OTF 或 TTC 文件作为 app-local 运行时 fallback:

```powershell
Get-FileHash "$skillDir\assets\arialuni_sdf_u2019" -Algorithm SHA256
python unity-text-locator\scripts\install_tmp_chinese_font_fix.py "path\to\GameFolder" `
--runtime-font-file "path\to\NotoSansCJKsc-Regular.otf" `
--out-dir "path\to\GameFolder\_translation\unity-text-report\font-fix" `
--dry-run
```

不要把字体资产提交进 git;它只需要留在本机的 skill 目录里。
检查 dry-run 报告后,移除 `--dry-run` 应用。安装器把字体复制到游戏 `_Data/ChineseFontFixer/Fonts/` 私有目录,与 DLL 和注入 JSON 一起备份、提交和失败回滚。报告会记录字体来源、目标、大小与 SHA-256。

静态 TMP font bundle 不是通用替代品。只有目标 Unity Editor 和 TMP package 版本精确匹配时才可作为候选,并且必须先做单字体、单界面 canary。发布 Noto 字体包的许可和 manifest 要求见 [release-assets.md](release-assets.md)。
Loading
Loading