오픈소스 CLI 도구

코드베이스를 위한 에이전트 기반 로컬라이제이션

l10n은 LLM으로 콘텐츠를 번역하고, 모든 것을 저장소 내에 유지하며, 로컬에서 출력을 검증하고, 외부 플랫폼을 거치지 않고 팀이 검토할 수 있는 초안을 생성합니다.

시작하기 작동 방식

Tuist가 이 도구를 만든 이유

Crowdin 과 Weblate 를 사용해 봤습니다. 콘텐츠를 내보내고 가져오는 과정이 작업 속도를 늦췄고, 자체 검증을 루프에 넣을 수 없었습니다. 코드와 동일한 워크플로우를 원했습니다: 변경, 테스트, 리뷰, 배포.

이제 번역은 제자리에서 생성되고, 기존 도구로 검사되며, 필요한 경우에만 사람이 검토합니다.

작동 방식

01
에이전트에 컨텍스트 제공

콘텐츠 옆에 L10N.md 컨텍스트 파일을 추가하세요. l10n은 의존성을 추적하여 컨텍스트나 콘텐츠가 변경되면 영향받는 번역만 재생성합니다.

02
모델 선택

에이전트 세션을 조율할 모델과 정확하게 번역할 모델을 각각 선택하세요. OpenAI 호환 엔드포인트, Vertex AI, 또는 자체 호스팅 모델을 사용할 수 있습니다.

03
에이전트가 스스로 검증

에이전트는 내장된 구문 검사와 사용자가 정의한 커스텀 명령어를 사용합니다. 각 번역 후 검증을 실행하고 오류 시 재시도하므로, 검토 전에 출력이 정확합니다.

Tools

Agents use tools to automate verification after every translation.

Syntax validators

Parse output to ensure it is valid before it is saved.

  • JSON
  • YAML
  • PO
  • Markdown frontmatter

Preserve checks

Guarantee critical tokens survive translation.

  • Code blocks
  • Inline code
  • URLs
  • Placeholders

Custom commands

Bring your own validators with check_cmd and check_cmds.

  • Linters
  • Compilers
  • Schema validators

Tool failures trigger retries until the output is valid.

설정은 저장소에 존재

L10N.md

TOML 프론트매터에서 번역 소스, 대상, 출력 패턴을 정의하세요.

+++
[[translate]]
source = "site/src/_data/home.json"
targets = ["es", "de", "ko", "ja", "zh-Hans", "zh-Hant"]
output = "site/src/_data/i18n/{lang}/{basename}.{ext}"
+++

# Context for the translating agent...

CLI 명령어

번역, 검증, 업데이트 필요 항목 추적을 수행합니다.

  • l10n translate 번역 생성
  • l10n status 누락되거나 오래된 출력 보고
  • l10n check 출력 구문 검증
  • l10n clean 오래된 번역 출력 제거

--force 를 사용하면 전체를 다시 번역합니다.

실제 워크플로우를 위해 설계

#

컨텍스트 인식 해싱

소스 콘텐츠나 상위 L10N.md 컨텍스트가 변경되면 번역이 업데이트됩니다.

✓

검증 훅

JSON, YAML, PO 구문 검사와 선택적 외부 린트 명령어를 지원합니다.

»

에이전트 파이프라인

조율자와 번역자 모델을 분리하고 검증 오류 시 재시도합니다.

휴먼 리뷰 지원

초안을 빠르게 생성하고, 필요할 때 검토하며, 모든 것을 Git에 유지합니다.

점진적 개선

번역이 처음부터 완벽할 필요는 없습니다. 코드처럼 반복을 통해 개선됩니다.

LLM의 초안은 구조적으로 정확하지만 뉘앙스, 어조, 도메인 특화 표현을 놓칠 수 있습니다. 이는 의도된 설계입니다. 각 리뷰 사이클 — 풀 리퀘스트 코멘트, 업데이트된 컨텍스트 파일, 용어집 수정 — 이 다음 번역 실행에 반영됩니다. 품질은 한 번에 완성되는 것이 아니라 반복적인 패스를 통해 수렴합니다.

초안

LLM이 컨텍스트 파일을 기반으로 구조적으로 유효한 첫 번째 패스를 생성합니다.

리뷰

팀이 코드 리뷰처럼 풀 리퀘스트를 통해 문제를 지적합니다.

개선

업데이트된 컨텍스트와 용어집 수정이 다음 실행에 반영되어 품질 격차를 줄입니다.

수렴

각 사이클이 프로덕션 품질과의 거리를 좁힙니다. 시스템이 제품의 목소리를 학습합니다.

이는 제조업의 카이젠, 전문 번역의 사후 편집(PEMT), 공학의 축차 근사와 동일한 원칙을 따릅니다: 충분히 좋은 기준선에서 시작하여 사람의 판단을 루프에 포함시켜 체계적으로 개선합니다.

FAQ

기존 번역 도구와 어떻게 다른가요?

기존 도구는 번역 메모리(유사도로 매칭되는 과거 번역의 정적 데이터베이스)에 의존합니다. l10n은 이를 메모리로서의 LLM 컨텍스트로 대체합니다: 에이전트가 읽고 학습하며, 팀이 시간이 지남에 따라 반복 개선할 수 있는 컨텍스트 파일입니다. 퍼지 매치를 조회하는 대신, 에이전트가 제품의 어조, 용어, 관례를 이해합니다. 그리고 개발자가 컴파일이나 린팅으로 코드 변경을 검증하듯이, 에이전트도 동일한 환경의 도구로 번역을 검증합니다. CI나 로컬에서 실행하면 에이전트가 린터, 컴파일러, 검증기를 사용해 자체 출력을 수정합니다.

모델을 직접 준비해야 하나요?

네. l10n은 CLI 도구이지 호스팅 서비스가 아닙니다. OpenAI 호환 엔드포인트, Vertex AI, 또는 자체 모델을 지정합니다. 비용, 데이터, 품질을 직접 통제합니다.

사람은 번역을 어떻게 검토하나요?

현재 리뷰어는 풀 리퀘스트와 diff를 통해 번역된 콘텐츠를 확인하고, 필요시 컨텍스트 파일을 업데이트하여 재번역을 트리거할 수 있습니다. 향후에는 개발자가 Codex 같은 코딩 에이전트와 작업하듯이, 리뷰어도 로컬에서 l10n을 실행하여 루프의 일부가 될 것으로 예상합니다.

업데이트