React에서 로컬라이제이션 간소화: `translation-service-react` 내부 살펴보기

Source: Dev.to

현대 프론트엔드 애플리케이션에서 국제화(i18n)와 로컬라이제이션을 관리하는 일은 종종 복잡한 작업이 될 수 있습니다. React 생태계에서 작업하는 개발자들에게 translation-service-react 라이브러리는 구조화되고 반응적이며 매우 동적인 다국어 콘텐츠 처리 방식을 제공합니다.

Arpad K.(@arpad1337)가 만들었으며 2025년에 MIT 라이선스로 공개된 이 경량 도구는 React 번역 파이프라인을 위한 깔끔한 즉시 사용 가능한 솔루션을 제공합니다.

Overview

translation-service-react는 싱글톤 패턴을 사용해 TranslationService 클래스를 구현함으로써 애플리케이션 전체에서 단일하고 전역적으로 일관된 언어 상태를 보장합니다. 반응형 상태 관리는 RxJS에 의해 구동되며, ReplaySubject(버퍼 크기 1)를 통해 언어 변경을 방송합니다. 컴포넌트는 getCurrentLanguage()를 Observable로 구독하여 언어 토글에 즉시 반응할 수 있습니다.

Language Detection & Persistence

서비스가 초기화될 때 다음과 같은 스마트 감지 순서를 따릅니다:

1. Local Storage Check – localStorage에 이전에 저장된 언어 선택이 있는지 확인하여 세션 간 지속성을 유지합니다.
2. Browser Native Language Matching – 저장된 선호도가 없을 경우 navigator.language를 검사합니다. 기본적으로 라이브러리는 영어와 프랑스어를 지원하며, 정규식 /^fr\b/와 매치되면 자동으로 프랑스어를 설정하고, 그렇지 않으면 영어를 사용합니다.

Translation Features

Compound Key Traversal

번역은 중첩된 사전 객체에 저장됩니다. 키는 점 표기법(e.g., page_1.title)을 사용해 접근할 수 있습니다. 키가 없을 경우 서비스는 대괄호로 감싼 키(e.g., [page_1.title])를 반환하여 개발 중에 누락된 번역을 쉽게 식별할 수 있게 합니다.

TranslationToken & HTML Parsing

해결된 번역은 TranslationToken 클래스에 래핑됩니다. html-to-react 파서를 사용해 토큰은 원시 HTML 문자열을 안전한 React 노드로 자동 변환합니다.

Rich Variable Interpolation

TranslationToken은 .interpolate() 메서드를 제공하여 {{variable}}과 같은 대괄호 변수들을 스캔합니다. 전달할 수 있는 값은 다음과 같습니다:

• 일반 문자열
• React 요소를 반환하는 함수(라이브러리는 ReactDOMServer.renderToString()을 사용해 컴포넌트를 번역 문자열에 삽입합니다)

Integration Example

import { TranslationService } from './translation-service-react';

// Access the singleton instance
const ts = TranslationService.instance;

// Programmatically update the active language
ts.setLanguage(value as Language);

// Resolving a simple nested string directly into a React Node
{ts.resolve('page_1.title')};

// Resolving a string that contains a variable (e.g., "Hello {{variable}}!")
{ts
  .resolve('text.with.variable')
  .interpolate({ variable: value })
  .toString()}

Conclusion

RxJS 상태 관리, 원활한 localStorage 통합, HTML 파싱, 고급 React 노드 인터폴레이션을 하나의 패키지에 묶음으로써 translation-service-react는 React 애플리케이션 로컬라이제이션에 일반적으로 수반되는 보일러플레이트 코드를 추상화합니다. 단순 텍스트 교체든 복잡한 HTML이 포함된 문자열이든, 프런트엔드를 진정으로 글로벌하게 만들기 위한 도구를 제공합니다.

GitHub Repository – translation-service-react