software

자동화된 i18n 테스트를 위한 Pseudo-localization

발행: (2025년 12월 23일 오후 07:02 GMT+9)
12 min read
원문: Dev.to

Source: Dev.to

위에 제공된 링크의 본문을 번역하고 싶으신가요? 번역하려는 실제 텍스트(본문)를 알려주시면 한국어로 번역해 드리겠습니다.

Pseudo‑localization이란 무엇인가?

Pseudo‑localization은 애플리케이션의 원본 텍스트를 변형된 가짜 언어로 바꾸어 번역 후 UI가 어떻게 동작하는지를 모방하는 과정입니다. 이는 QA 엔지니어와 개발자가 개발 주기의 초기 단계에서 i18n 문제를 식별하는 데 도움을 줍니다.

Example of using pseudo‑localization

잠재적인 국제화 문제를 식별하기 위해 pseudo‑localization을 사용한 예시입니다. 양쪽 모두 글꼴과 크기가 동일하지만, 다른 스크립트를 지원하려면 종종 더 많은 공간이 필요합니다.

왜 의사 현지화가 유용한가

Pseudo‑localization은 i18n 문제를 조기에 발견하는 데 도움이 됩니다:

  • 레이아웃 파손 – 텍스트 확장(독일어, 핀란드어 등)은 영어보다 30 %–40 % 더 길어질 수 있습니다.
  • 인코딩 문제 – 악센트가 있는 문자는 UTF‑8 문제를 드러냅니다.
  • 번역 가능성 – 하드코딩된 문자열은 그대로 남아 있어 쉽게 식별할 수 있습니다.
  • 플레이스홀더 처리 – {{name}}와 같은 동적 콘텐츠는 그대로 유지되어야 합니다.
  • 길이 제한 – 더 많은 공간이 필요한 언어를 위해 UI 구성 요소의 안전한 길이 제한을 정의합니다.

QA 자동화 전략

1. 악센트 및 비라틴 문자

라틴 문자를 악센트가 있는 형태나 다른 스크립트로 교체하여 문자 인코딩 및 폰트 지원을 테스트합니다.

Example: “Save” → “Šàvē”

QA 체크: 모든 문자가 올바르게 표시되는지, 인코딩 문제로 인해 깨지는 것이 없는지 확인합니다.

2. 텍스트 확장 시뮬레이션

각 문자열을 약 30 %–40 % 정도 자동으로 확장하여 긴 언어를 흉내냅니다. 시각적 마커로 감싸서 클리핑 감지를 쉽게 합니다.

Example: “Save” → ⟦Šàvēēēēē⟧

QA 체크: 자동 스크린샷 비교를 사용해 UI 오버플로, 클리핑 또는 정렬 오류를 찾아냅니다.

3. 플레이스홀더 스트레스 테스트

보간 변수(플레이스홀더)를 눈에 보이는 마커로 교체하여 번역 과정에서 보존되는지 확인합니다.

Example: “You have {{count}} items” → “You have items”

QA 체크: 회귀 테스트를 실행하고, 마커가 누락되었거나 잘못 이스케이프된 경우 테스트를 실패 처리합니다.

4. RTL 시뮬레이션

유니코드 제어 문자를 사용해 오른쪽‑왼쪽(RTL) 마커로 텍스트를 감싸 아랍어 또는 히브리어를 시뮬레이션합니다.

QA 체크: RTL 언어에 대한 정렬, 텍스트 방향 및 미러링이 올바른지 확인합니다.

5. CI/CD 통합

자동화 테스트 파이프라인에 의사‑현지화를 추가하여 i18n 문제를 프로덕션에 배포되기 전에 잡아냅니다.

QA 체크: 누락된 번역, 깨진 플레이스홀더 또는 레이아웃 문제가 감지되면 배포를 차단합니다.

pseudo‑l10n 패키지를 사용한 자동화

pseudo‑l10n npm 패키지는 JSON 번역 파일에 대한 의사 현지화를 자동화하여 i18n 테스트를 개발 워크플로에 쉽게 통합할 수 있게 해줍니다.

주요 기능

  • 텍스트 확장 – 번역 문자열을 30 %–40 % 정도 길게 시뮬레이션합니다.
  • 악센트 문자 – UTF‑8 인코딩 및 폰트 지원을 테스트합니다.
  • 시각적 마커 – ⟦…⟧ 로 문자열을 감싸서 번역되지 않았거나 잘린 텍스트를 쉽게 찾을 수 있습니다.
  • 플레이스홀더 처리 – {{name}}, {count}, %key% 등과 같은 플레이스홀더를 그대로 유지합니다.
  • RTL 시뮬레이션 – 유니코드 제어 문자를 사용해 오른쪽‑왼쪽 언어를 시뮬레이션합니다.

설치

# 전역 설치 (CLI 사용)
npm install -g pseudo-l10n
# 개발 의존성으로 설치
npm install --save-dev pseudo-l10n

기본 사용법

소스 번역 파일을 의사‑현지화된 버전으로 변환합니다:

pseudo-l10n input.json output.json

예시 변환

입력 (en.json):

{
  "welcome": "Welcome to our application",
  "greeting": "Hello, {{name}}!",
  "itemCount": "You have {{count}} items"
}

출력 (pseudo-en.json):

{
  "welcome": "⟦Ŵëļçõɱë ţõ õür àƥƥļïçàţïõñēēēēēēēēēēēēēēēēēē⟧",
  "greeting": "⟦Ĥëļļõēēēēēē, {{name}}!ēēēēē⟧",
  "itemCount": "⟦Ŷõü ĥàṽë {{count}} ïţëɱšēēēēēēēēēēēēēēēē⟧"
}

고급 기능

사용자 정의 확장

pseudo-l10n en.json pseudo-en.json --expansion=30

RTL 시뮬레이션

pseudo-l10n en.json pseudo-en.json --rtl

예시:

{
  "greeting": "⟦Ĥëļļõēēēēēē, !ēēēēē⟧"
}

플레이스홀더 형식

이 패키지는 다양한 i18n 라이브러리에서 사용되는 플레이스홀더 구문을 지원합니다:

# i18next (default)
pseudo-l10n en.json pseudo-en.json --placeholder-format="{{key}}"

# Angular / React Intl
pseudo-l10n en.json pseudo-en.json --placeholder-format="{key}"

# sprintf style
pseudo-l10n en.json pseudo-en.json --placeholder-format="%key%"

요약

pseudo‑l10n을 개발 및 CI/CD 파이프라인에 통합하면 다음을 자동으로 감지할 수 있습니다:

  • 텍스트 확장으로 인한 레이아웃 깨짐
  • 비라틴 문자 인코딩 문제
  • 누락되었거나 형식이 잘못된 플레이스홀더
  • RTL‑전용 UI 문제

이 사전 예방적 접근 방식은 보다 원활한 현지화 프로세스와 더 견고하고 전 세계적으로 준비된 애플리케이션을 보장합니다. 즐거운 테스트 되세요!

프로그래밍 방식 사용

Node.js 스크립트나 빌드 프로세스에서 pseudo‑l10n을 프로그래밍 방식으로 사용하세요:

const { generatePseudoLocaleSync, pseudoLocalize } = require('pseudo-l10n');

// Generate a pseudo‑localized JSON file
generatePseudoLocaleSync('en.json', 'pseudo-en.json', {
  expansion: 40,
  rtl: false
});

// Pseudo‑localize a single string
const result = pseudoLocalize('Hello, {{name}}!');
console.log(result);
// Output: ⟦Ĥëļļõēēēēēēēēēēēēē, {{name}}!ēēēēē⟧

워크플로우에 통합하기

npm 스크립트

package.json 스크립트에 pseudo‑localization 생성을 추가합니다:

{
  "scripts": {
    "pseudo": "pseudo-l10n src/locales/en.json src/locales/pseudo-en.json",
    "pseudo:rtl": "pseudo-l10n src/locales/en.json src/locales/pseudo-ar.json --rtl"
  }
}

빌드 프로세스 통합

빌드 프로세스의 일환으로 pseudo‑locales를 생성합니다:

// build.js
const { generatePseudoLocaleSync } = require('pseudo-l10n');

// Generate pseudo‑locales as part of build
generatePseudoLocaleSync(
  './src/locales/en.json',
  './src/locales/pseudo-en.json',
  { expansion: 40 }
);
generatePseudoLocaleSync(
  './src/locales/en.json',
  './src/locales/pseudo-ar.json',
  { rtl: true }
);

CI/CD 파이프라인 통합

pseudo‑localization을 지속적 통합 파이프라인에 통합합니다:

# .github/workflows/test.yml
- name: Generate pseudo‑locales
  run: |
    npm install -g pseudo-l10n
    pseudo-l10n src/locales/en.json src/locales/pseudo-en.json

- name: Run i18n tests
  run: npm run test:i18n

테스트 전략

  1. 빌드 과정에서 의사 로케일(pseudo‑locale)을 생성합니다.
  2. 의사 로케일을 애플리케이션에 추가합니다(예: 언어 선택기에서).
  3. 의사 로케일을 활성화한 상태에서 애플리케이션을 테스트합니다.
  4. UI를 검토하여 일반적인 i18n 문제를 확인합니다.

확인할 항목

  • Missing ⟦⟧ markers – 번역되지 않은 문자열(하드코딩된 텍스트).
  • Cut‑off markers – 텍스트 잘림 또는 UI 오버플로우.
  • Broken layout – 텍스트 확장을 위한 공간 부족.
  • Garbled text – 인코딩 문제 또는 폰트 지원 부족.
  • Wrong text direction – RTL 문제(오른쪽에서 왼쪽으로 쓰는 의사 로케일의 경우).

의사 현지화(pseudo‑localization)는 국제화 문제를 프로덕션에 도달하기 전에 잡아내는 필수 테스트 기법입니다. pseudo‑l10n 패키지를 사용해 의사 현지화 테스트를 자동화하면 애플리케이션이 전 세계 사용자를 위해 진정으로 준비되었는지 확인할 수 있습니다.

테스트에서 실제 번역으로

일단 의사 현지화(pseudo‑localization)로 i18n 구현을 검증했다면, 실제 사용자들을 위해 애플리케이션을 번역할 차례입니다. 여기서 AI 기반 번역 서비스인 **l10n.dev**가 활용됩니다.

프로덕션 번역에 l10n.dev를 선택하는 이유

  • 플레이스홀더, 포맷, 구조를 그대로 유지합니다 — 테스트 중 의사 현지화(pseudo‑l10n)가 보호하는 것과 동일합니다.
  • 문맥을 고려한 AI 번역으로 165개 언어를 지원합니다.
  • 복수형, 인터폴레이션, 특수 문자 등을 자동으로 처리합니다.
  • API, npm 패키지 ai‑l10n, 혹은 **자동 현지화를 위한 GitHub Action**을 통해 CI/CD 연동을 제공합니다.
  • **VS Code 확장 프로그램**과 수동 **i18n 번역**을 위한 웹 UI를 제공합니다.

완전한 i18n 워크플로우

  1. 테스트 i18n 구현을 pseudo‑l10n으로 수행하여 문제를 조기에 발견하세요.
  2. 수정 테스트 중에 발견된 레이아웃, 인코딩 또는 플레이스홀더 문제를 해결하세요.
  3. 번역 i18n 파일을 l10n.dev를 사용해 프로덕션 수준 번역으로 전환하세요.

읽어 주셔서 감사합니다!

Back to Blog

관련 글

더 보기 »