목차
엔터프라이즈 규모에서 번역을 관리하는 것은 소규모 앱에서 수십 개의 키를 처리하는 것과는 근본적으로 다른 과제입니다. 제품이 20개 언어, 50개 네임스페이스, 수천 개의 번역 키에 걸쳐 있을 때, 수동 워크플로우는 그 자체의 무게를 견디지 못하고 무너집니다. 모든 용어 변경은 수백 개의 문자열에 연쇄적으로 영향을 미칩니다. 모든 신규 언어 출시는 모든 단일 키를 수정해야 합니다. 모든 릴리스 주기는 전체 변경 범위를 포괄하는 게시 작업을 요구합니다.
이 가이드에서는 Better i18n의 배치 작업이 이러한 문제를 어떻게 해결하는지 살펴봅니다 — 번역 편집기의 내장 대량 작업부터 AI 기반 번역, CMS 대량 관리, MCP 도구 자동화까지.
세 가지 핵심 배치 작업
번역 편집기는 효율적인 현지화 관리의 기반을 형성하는 세 가지 배치 작업을 제공합니다.
번역 일괄 업데이트
가장 일반적인 대량 작업은 여러 키에 걸쳐 번역을 동시에 업데이트하는 것입니다. 실제 시나리오를 생각해 보십시오. 회사가 전체 제품에서 "Workspace"를 "Team Space"로 리브랜딩합니다. 배치 작업 없이는 누군가가 모든 언어에서 해당 용어를 포함하는 모든 키를 찾아 업데이트해야 합니다.
일괄 업데이트를 사용하면 영향을 받는 키를 선택하고 변경을 적용하면 선택한 모든 언어에 전파됩니다. 작업은 원자적입니다: 모든 업데이트가 성공하거나 아무것도 성공하지 않으므로, 부분적으로 업데이트된 UI가 발생하는 일이 없습니다.
키 일괄 삭제
사용하지 않는 번역 키를 정리하는 것은 팀이 지루하다는 이유로 자주 소홀히 하는 필수 유지 관리 작업입니다. 기능이 더 이상 사용되지 않고, A/B 테스트가 종료되며, 오래된 문자열이 축적됩니다. 일괄 삭제를 통해 여러 키를 선택하고 한 번의 작업으로 제거할 수 있습니다. 작업은 네임스페이스 경계를 존중하므로, 다른 영역에 실수로 영향을 줄 걱정 없이 앱의 한 영역을 정리할 수 있습니다.
번역 일괄 게시
번역은 생성, 번역, 검토, 게시의 수명 주기를 거칩니다. 게시 단계는 번역을 CDN에 푸시하거나 GitHub 리포지토리와 동기화합니다. 일괄 게시를 통해 키별로 게시하는 대신 검토된 번역 전체 세트를 한 번에 라이브로 푸시할 수 있습니다. 이는 모든 번역 변경 사항이 동시에 라이브로 전환되기를 원하는 조율된 릴리스에서 특히 중요합니다.
translateBatch를 사용한 AI 대량 번역
translateBatch 도구는 배치 작업과 AI가 만나는 곳입니다. 단일 요청으로 최대 500개의 키를 번역할 수 있으며, 범위와 대상에 대한 정밀한 제어가 가능합니다.
매개변수가 함께 작동하는 방식은 다음과 같습니다:
- targetLanguages[] 는 번역을 생성할 언어를 정의합니다. 하나의 새 언어 또는 한 번에 열두 개를 대상으로 할 수 있습니다.
- scope 는 범위를 결정합니다 — "all"은 프로젝트의 모든 키를 포괄하고, "namespace"는 범위를 좁힙니다.
- namespaces[] 는 scope가 "namespace"로 설정된 경우 포함할 네임스페이스를 정확히 지정합니다.
- maxKeys 는 요청당 1~500개의 키로 배치 크기를 제어합니다.
AI 대량 번역 사용 시기
AI 번역은 첫 번째 단계로서 탁월한 성능을 발휘합니다. 빠르고 일관성이 있으며 대량을 처리합니다. 이상적인 워크플로우는 다음과 같습니다:
translateBatch를 실행하여 번역되지 않은 모든 키의 초기 번역을 생성합니다- 번역 편집기를 사용하여 AI 생성 번역을 검토하고 다듬습니다
- 검토된 번역을 일괄 게시합니다
이 세 단계 워크플로우는 일주일에 걸친 수동 번역 작업을 하루의 검토 작업으로 전환합니다.
CMS 대량 작업
Better i18n의 콘텐츠 관리 시스템을 사용하는 경우, 구조화된 콘텐츠에 대한 병렬 대량 기능에 액세스할 수 있습니다.
bulkUpdateEntryStatus 는 단일 작업으로 여러 콘텐츠 항목을 상태 간에 이동합니다 — 초안, 게시됨, 또는 보관됨. 수십 개의 오래된 항목을 보관하거나 검토된 콘텐츠 배치를 동시에 게시해야 하는 콘텐츠 감사 중에 매우 유용합니다.
bulkDeleteEntries 는 여러 콘텐츠 항목을 한 번에 제거합니다. 제품 라인을 더 이상 사용하지 않거나 테스트 콘텐츠를 정리할 때 상당한 수동 작업을 절약합니다.
proposeContentEntries 는 AI를 사용하여 단일 요청으로 최대 20개의 구조화된 콘텐츠 항목을 생성합니다. 각 항목에는 번역이 완성되어 있어, 새로운 제품 영역이나 시장 출시를 위한 콘텐츠 라이브러리 부트스트랩에 강력한 도구입니다.
개발자 워크플로우를 위한 MCP 대량 도구
MCP(Model Context Protocol)는 모든 대량 작업을 프로그래밍 가능한 도구로 노출하여 UI가 제공하는 것을 넘어서는 자동화를 가능하게 합니다.
createKeys — 키 일괄 생성
단일 API 호출로 초기 번역과 함께 수백 개의 번역 키를 생성합니다. 이는 새로운 기능 영역을 설정하거나 외부 시스템에서 번역을 가져올 때 선택하는 도구입니다. 각 키에는 여러 언어의 번역이 포함될 수 있으므로, 단일 작업으로 완전히 번역된 네임스페이스를 생성할 수 있습니다.
updateKeys — 번역 일괄 업데이트
여러 키와 언어에 걸쳐 기존 번역을 업데이트합니다. 도구는 대상 키가 존재하는지 확인하고 네임스페이스 불일치에 대해 경고합니다 — 잘못된 네임스페이스에 중복 키가 실수로 생성되는 것을 방지하는 중요한 가드레일입니다.
deleteKeys — 키 일괄 제거
더 이상 사용되지 않는 키를 프로그래밍 방식으로 제거합니다. 이는 코드베이스에서 더 이상 참조되지 않는 키를 자동으로 정리하는 CI/CD 파이프라인에 자연스럽게 통합됩니다.
publishTranslations — CDN 및 GitHub에 일괄 게시
전체 네임스페이스의 번역을 한 번에 라이브로 푸시합니다. 게시 작업은 높은 처리량을 위해 설계되었습니다 — PUBLISH_BATCH 메시지 유형을 사용하여 내부적으로 배치 처리하고 batch_publish 작업 유형을 통해 처리하므로, 수천 개의 키를 게시하더라도 워크플로우가 차단되지 않습니다.
실제 시나리오: 5,000개 키 마이그레이션
구체적인 엔터프라이즈 시나리오를 살펴보겠습니다. 팀이 번역 아키텍처를 재구성하고 있습니다 — 단일 "common" 네임스페이스를 "billing", "settings", "onboarding"과 같은 도메인 특화 네임스페이스로 분할합니다.
1단계: 내보내기 및 매핑. listKeys를 사용하여 "common" 네임스페이스의 모든 키를 가져옵니다. 새로운 아키텍처를 기반으로 각 키를 대상 네임스페이스에 매핑합니다.
2단계: 일괄 생성. createKeys를 사용하여 기존 번역이 모두 이전된 새 네임스페이스에 키를 생성합니다. 최적의 처리량을 위해 200-300개의 키 배치로 처리합니다.
3단계: 검증. 각 새 네임스페이스에서 listKeys를 사용하여 모든 키가 번역과 함께 올바르게 이전되었는지 확인합니다.
4단계: 일괄 게시. 각 새 네임스페이스에 publishTranslations를 사용하여 재구성된 번역을 CDN에 푸시합니다.
5단계: 정리. 코드베이스가 새 네임스페이스를 참조하도록 업데이트되면, deleteKeys를 사용하여 "common"에서 이전 키를 제거합니다.
전체 마이그레이션 — 15개 언어에 걸친 5,000개의 키 — 은 스프린트를 소비하는 대신 오후 시간에 완료됩니다.
실제 시나리오: 대량 언어 출시
제품이 지원 언어를 5개에서 12개로 확장하고 있습니다. 즉, 모든 네임스페이스에 7개의 새 언어를 추가해야 합니다.
1단계: AI 첫 번째 단계. 7개의 새 대상 언어, "all"로 설정된 범위, 500으로 설정된 maxKeys로 translateBatch를 실행합니다. 2,000개의 키가 있는 프로젝트의 경우 4번의 배치가 필요합니다.
2단계: 우선순위 검토. 고객 대면 네임스페이스를 먼저 사람이 검토하는 데 집중합니다. 번역 편집기의 일괄 업데이트를 사용하여 검토자 수정을 효율적으로 적용합니다.
3단계: 단계적 게시. 트래픽이 가장 높은 영역부터 시작하여 한 번에 하나의 네임스페이스를 일괄 게시합니다. 다음 배치를 게시하기 전에 문제가 없는지 모니터링합니다.
4단계: 지속적인 적용 범위. 개발 중에 추가된 새 키에 대해 자동화된 translateBatch 실행을 설정하여 새 언어가 절대 뒤처지지 않도록 합니다.
규모에서의 성능 및 안전성
엔터프라이즈 규모의 배치 작업에는 가드레일이 필요합니다. Better i18n의 대량 도구에는 몇 가지 안전 메커니즘이 포함되어 있습니다:
- 네임스페이스 유효성 검사 는 잘못된 네임스페이스에 키가 생성되는 것을 방지합니다 — 유령 중복 키로 이어지는 일반적인 자동화 오류입니다.
- 엔터티 간 충돌 경고 는 생성하려는 키가 다른 네임스페이스에 이미 존재하는 경우 알려줍니다.
- 원자적 작업 은 배치 업데이트가 완전히 성공하거나 완전히 롤백되도록 보장합니다 — 부분 상태가 없습니다.
- 비동기 처리 는 대규모 게시 배치에 대해 팀이 배포 완료를 기다리며 차단되지 않음을 의미합니다.
배치 작업 시작하기
현재 번역을 수동으로 관리하고 있다면, 설정이 필요 없고 즉각적인 생산성 향상을 제공하는 번역 편집기의 배치 작업부터 시작하십시오. 규모가 커짐에 따라 MCP 대량 도구를 개발 워크플로우에 통합하여 프로그래밍 방식의 제어를 실현하십시오. 그리고 AI 대량 번역을 사용하여 새 언어를 추가할 때 콜드 스타트 문제를 제거하십시오.
엔터프라이즈 번역 관리가 느릴 필요는 없습니다. 적절한 배치 도구를 사용하면, 현지화 워크플로우가 제품만큼 빠르게 확장됩니다.
