Angular i18n에서 누락된 조각

Source: Dev.to

(번역할 텍스트를 제공해 주시면 한국어로 번역해 드리겠습니다.)

실제로 문제가 발생하는 곳

프로덕션 애플리케이션에서는 번역 파일이 일시적인 빌드 산출물이 아닙니다.

이 파일들은 사람과 외부 도구가 편집하는 장기 보존 문서입니다.

일반적인 로케일 파일에는 번역된 텍스트보다 훨씬 많은 내용이 포함됩니다:

• 번역가 메모
• 컨텍스트 그룹
• 승인 플래그
• 벤더‑별 메타데이터

…각 문자열에 의미와 이력을 부여하는 정보입니다.

하지만 messages.xlf가 변경될 때마다 팀은 위험한 워크플로우에 강제됩니다:

• 수동 XML 편집
• 복사‑붙여넣기 병합
• 로케일 파일 재생성
• XLIFF를 단순 키‑값 데이터로 가정하는 불안정한 스크립트

결과는 거의 항상 동일합니다: 묵시적인 데이터 손실.

• 메모가 사라집니다.
• 승인된 번역이 초기화됩니다.
• 컨텍스트가 손실됩니다.

그리고 번역가가 불만을 제기하거나 빌드가 실패할 때까지 아무도 눈치채지 못합니다.

Angular는 이 문제를 해결하지 못합니다. 대부분의 서드파티 도구도 마찬가지입니다.

What xlf-sync is designed to do

xlf-sync exists for a very specific purpose:

Keep messages..xlf files structurally in sync with messages.xlf without destroying anything that already exists.

It does not generate translations, “clean up” XML, or assume locale files can be recreated safely.

Instead, it treats them as valuable state that must be preserved.

• The source file remains the authority for what keys exist.
• Locale files remain the authority for everything else.

메타데이터가 진정한 차별점

대부분의 동기화 도구는 번역 단위를 처음부터 다시 만들며, 이 과정에서 도구가 이해하지 못하는 정보가 필연적으로 제거됩니다.

xlf-sync는 반대 접근 방식을 취합니다:

• 기존 번역 단위는 절대 재구성되지 않습니다.
• 번역 단위는 바이트 단위로 그대로 읽고 보존되며, 소스에 새로운 내용이 추가될 때만 확장됩니다.

2년 전에 번역가가 메모를 추가했다면 그대로 유지됩니다.
CAT 도구가 메타데이터를 추가했다면 살아남습니다.
항목이 승인된 것으로 표시되었다면 계속 승인된 상태를 유지합니다.

이는 편의 기능이 아니라, 도구의 핵심 보증입니다.

히스토리를 삭제하지 않고 변경 처리

애플리케이션은 지속적으로 변합니다: 문자열이 추가되고, 제거되며, 재구성됩니다.

xlf-sync는 한 가지 중요한 가정을 합니다: 제거가 곧 삭제를 의미하지는 않는다.

키가 소스 파일에서 사라질 때, 이를 어떻게 처리할지 직접 결정합니다. 다음 중 선택할 수 있습니다:

• 구식으로 표시한다.
• 전용 폐기 파일로 옮긴다.
• 명시적으로 삭제한다—정말로 원한다면.

암시적으로 일어나는 일은 없습니다. 실수로 사라지는 일도 없습니다.

이렇게 하면 리팩터링이 더 안전해지고, 기능이 일시적으로 제거될 때도 번역 작업을 보존할 수 있습니다.

실제 Angular 코드베이스를 위해 설계됨

많은 Angular 저장소는 깔끔한 그린필드 프로젝트가 아닙니다. 레거시 모듈, 마이그레이션, 혼합된 포맷을 포함하고 있습니다.

• xlf-sync는 XLIFF 1.2와 2.0을 모두 지원하며 파일별로 버전을 감지합니다.
• 동일 프로젝트에 두 포맷이 모두 존재해도 작동합니다.

이 덕분에 새로운 앱뿐만 아니라 역사가 있는 성숙한 시스템에서도 사용할 수 있습니다.

가시성과 자동화가 중요합니다

Angular의 CLI는 번역 상태에 대한 명확한 그림을 제공하지 않습니다.

xlf-sync는 다음을 제공함으로써 그 격차를 메웁니다:

• 빠른 콘솔 보고서.
• 로케일별 번역 커버리지를 시각화하는 독립형 HTML 대시보드.

이 대시보드는 특히 엔지니어링 팀 외부에서 유용합니다—XML 파일을 열지 않고도 번역 진행 상황을 확인할 수 있습니다.

자동화를 위해 check 명령은 i18n을 실제 CI 이슈로 전환합니다. 번역이 다음과 같은 경우 빌드를 실패시킬 수 있습니다:

• 누락된 경우
• 동기화되지 않은 경우
• 원본과 차이가 나는 경우

이렇게 하면 i18n이 사후 고려사항에서 품질 게이트로 이동합니다.

Angular이 아직 제공하지 않은 누락된 기능: 번역 대시보드

Angular의 i18n 도구는 파일을 제공하지만 전혀 가시성을 제공하지 않습니다. 다음을 알 수 없습니다:

• 어느 로케일이 뒤처져 있는지.
• 번역된 양이 얼마나 되는지.
• 실제로 누락된 부분이 어디인지.

xlf-sync는 독립형 HTML 대시보드로 이를 해결합니다.

npx xlf-sync dashboard

명령을 실행하면 모든 로케일에 대한 번역 커버리지를 시각화한 자체 포함 보고서가 생성됩니다. 보고서에는 다음이 표시됩니다:

• 존재하는 키 수.
• 번역된 키 수.
• 누락된 키.

XLIFF 파일을 열 필요 없이 확인할 수 있습니다.

대시보드가 정적 HTML이기 때문에 CI 파이프라인에 자연스럽게 통합됩니다. 팀에서는 종종 이를 빌드 아티팩트로 첨부하여 번역 진행 상황을 다른 품질 지표와 함께 가시화합니다.

테스트 보고서 및 커버리지 메트릭

This is not about eye candy.
이것은 눈요술이 아니라.

It’s about making i18n measurable.
i18n을 측정 가능하게 만드는 것입니다.

다른 도구와 차별점

Most tools treat locale files as derived output.
대부분의 도구는 로케일 파일을 파생된 결과물로 취급합니다.

xlf‑sync treats them as assets.
xlf‑sync는 이를 자산으로 다룹니다.

That single distinction explains its behavior:
그 단 하나의 차이가 동작 방식을 설명합니다:

• no destructive syncs
  파괴적인 동기화 없음
• no metadata loss
  메타데이터 손실 없음
• no silent rewrites
  무음 재작성 없음

It prioritizes safety over cleverness — which is exactly what long‑lived multilingual projects need.
영리함보다 안전성을 우선시합니다 — 이것이 오래 지속되는 다국어 프로젝트에 정확히 필요한 것입니다.

자세히 보기

• GitHub repository:
• Official documentation & landing page:
• npm package:

마무리 생각

Angular i18n handles extraction well.
Angular i18n은 추출을 잘 처리합니다.

Everything after that is left to the developer.
그 이후 모든 것은 개발자에게 맡겨집니다.

xlf‑sync doesn’t replace Angular’s tooling — it completes it.
xlf‑sync는 Angular 도구를 대체하지 않으며 — 그것을 보완합니다.

If your application has real translations, real translators, and real change, this problem will surface sooner or later.
애플리케이션에 실제 번역, 실제 번역가, 실제 변경이 있다면, 이 문제는 언젠가 나타날 것입니다.

xlf‑sync simply removes the risk from that moment onward.
xlf‑sync는 그 순간부터 위험을 단순히 제거합니다.