i18n-ally

i18n-ally

VS Code에서 다국어(i18n) 리소스 파일을 관리할 때 번역 키 자동 완성, 미번역/누락 탐지, 빠른 번역 편집 등 다양한 편의 기능을 제공하는 확장 프로그램이다.

• https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally
• https://github.com/lokalise/i18n-ally

ally 사용 목적

• 번역 키 자동 완성 및 미리보기
• 언어별 누락/미번역 키 실시간 탐지
• 매핑된 번역 키로 바로 이동 제공
  

ally 초기 세팅

1. 확장프로그램 다운로드 https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally

2. 프로젝트마다 localesPaths 등이 다를 수 있음으로 사용자 설정(모든 작업환경) 보다는 작업 영역에 setting 권장 .vscode/setting.json

   {
       "i18n-ally.localesPaths": ["src/static/language"], // 다국어 정의한 객체 파일이 존재하는 경로 기재
       "i18n-ally.sourceLanguage": "ko",
       "i18n-ally.displayLanguage": "ko",
       "i18n-ally.keystyle": "nested",
       "i18n-ally.enabledParsers": ["js", "ts", "json"]
   }

3. (optional) 다국어 resources type declare. (typescript만 해당)

   // i18next.d.ts
   import { resources } from '~language/i18n';
   
   // t() 함수에 다국어 key 입력 시, 존재 유무 판별 가능.
   declare module 'i18next' {
       interface CustomTypeOptions {
           resources: (typeof resources)['ko'];
       }
   }

   해당 전역 타입 설정 시 t 함수내 key 추론은 가능하지만, 키를 따로 상수로 보관하거나 동적으로 추론하는 경우 type error 발생. 신중히 정의해야함.

i18n-ally의 동작 방식

정적 파일 분석 (Static Analysis)

i18n-ally는 파일을 직접 파싱해서 번역 키와 값을 추출한다. TypeScript AST(Abstract Syntax Tree)를 분석해서 리터럴 객체의 구조를 읽는다.

동적 코드 인식 불가능

런타임 환경에 의해 동적으로 할당되는 값은 i18n-ally가 인식할 수 없다.
명확히 말하면 localesPaths에서 정의한 locale 파일에 동적할당되는 변수가 있을 경우 ally가 다국어 수집을 중지하는 것으로 판단되며, 이로 인해 ally에서 해당 locale 파일을 읽을 수 없다.

// ✅ i18n-ally가 인식 가능 (정적 구조)
export default {
  common: {
    search: '검색',
    cancel: '취소'
  }
};
// ✅ i18n-ally가 인식 가능한 동적 구조 (외부로부터 독립적인 연산)
const SERVICE_TITLE = [].map(() => {}).length === 0 ? '타이틀' : '제목';

export default {
    index: {
        title: SERVICE_TITLE // 타이틀
    },
}

// ❌ i18n-ally가 인식 불가능한 동적 구조 (외부값과 의존성이 있는 연산)
const SERVICE_TITLE = window.location ? '타이틀' : '제목';

export default {
    index: {
        title: SERVICE_TITLE
    },
}