Introduce
개요
gs-i18n은 Google Sheets와 i18next를 활용하여 다국어 번역을 효율적으로 관리할 수 있는 CLI 도구에요. 개발자와 번역가가 하나의 중앙화된 플랫폼에서 협업할 수 있도록 설계되었어요.
문제 정의
다국어 지원 과정에서 다음과 같은 문제들이 자주 발생해요.
- 개발자와 번역가 간의 협업 어려움: 개발자는 코드 작성, 번역가는 스프레드시트나 문서 사용
- 번역 키 관리의 복잡성: 새로운 키 추가, 기존 키 수정 시 동기화 문제
- 수동 업데이트의 비효율성: JSON 파일과 스프레드시트 간의 수동 복사 붙여넣기
- 번역 누락 위험: 개발 과정에서 추가된 키가 번역되지 않은 채로 배포
해결책
gs-i18n은 이러한 문제들을 다음과 같은 방식으로 해결해요.
1. 중앙화된 번역 관리
- Google Sheets를 Single Source of Truth로 활용
- 모든 번역 데이터를 한 곳에서 관리
- 실시간 협업 가능
2. 양방향 동기화
- 코드 → 스프레드시트: 개발자가 추가한 번역 키를 자동으로 스프레드시트에 업로드
- 스프레드시트 → 코드: 번역가가 작업한 내용을 자동으로 JSON 파일에 다운로드
- 충돌 없는 안전한 동기화
3. 자동화된 워크플로우
- i18next-scanner를 활용한 번역 키 자동 추출
- 인터랙티브 CLI를 통한 간편한 작업 실행
- 일관된 파일 구조 자동 생성
주요 기능
스프레드시트 정보 조회
연결된 Google Spreadsheet의 기본 정보와 시트 목록을 확인할 수 있어요.
i18next-scanner 설정 생성
프로젝트에 맞는 i18next-scanner 설정 파일을 인터랙티브하게 생성해요.
다국어 파일 스캔
코드베이스에서 사용된 번역 키를 자동으로 추출하여 JSON 파일을 생성해요.
번역 업로드
로컬 JSON 파일의 번역 데이터를 Google Sheets에 업로드해요.
번역 다운로드
Google Sheets의 번역 데이터를 로컬 JSON 파일로 다운로드해요.
작동 원리
- 개발자가 코드에서 번역 키 사용 (
t('welcome')
) - i18next-scanner가 코드 스캔하여 번역 키 추출
- gs-i18n upload로 JSON → Google Sheets 동기화
- 번역가가 Google Sheets에서 번역 작업
- gs-i18n download로 Google Sheets → JSON 동기화
- 번역된 애플리케이션 배포
워크플로우 예시
1. 초기 설정
bash
# 설정 파일 생성
npx gs-i18n
→ gs-i18n.json 구성
→ "i18next-scanner 파일 생성하기" 선택
# 언어 선택, 기본 언어 설정
→ 한국어, 영어, 일본어 선택
→ 기본 언어: 한국어
2. 개발 중 번역 관리
bash
# 1. 코드에서 번역 키 추가
const MyComponent = () => {
const { t } = useTranslation();
return <h1>{t('welcome')}</h1>;
};
# 2. 스캔 실행
npx gs-i18n
→ "다국어 관련 기본 파일 구성하기" 선택
# 3. 스프레드시트에 업로드
npx gs-i18n
→ "다국어 코드 시트에 반영하기" 선택
# 4. 번역가가 Google Sheets에서 작업
# 5. 번역 다운로드
npx gs-i18n
→ "시트 번역 내용 코드에 반영하기" 선택
장점
개발자 관점
- 번역 키 관리
- 타입 안전성 (TypeScript 지원)
- 기존 i18next 생태계와 호환
- 간편한 CLI 인터페이스
번역가 관점
- 친숙한 Google Sheets 환경
- 실시간 협업 가능
- 번역 진행 상황 한눈에 파악
- 이전 번역 기록 관리 용이
프로젝트 관점
- 번역 누락 위험 감소
- 개발-번역 프로세스 효율화
- 비용 효율적 (무료 Google Sheets 활용)
- 확장 가능한 구조
시작하기
gs-i18n을 사용하기 위해서는 다음 과정이 필요해요.
- Google Cloud Project 설정
- 서비스 계정 생성 및 권한 설정
- Google Spreadsheet 생성
gs-i18n.json
설정
자세한 사용법은 Usage 섹션을 참고해주세요.
기술 스택
- TypeScript: 타입 안전성과 개발 생산성
- Google APIs: Google Sheets 연동
- i18next-scanner: 번역 키 자동 추출
- @clack/prompts: 인터랙티브 CLI 구현
- @fxts/core: 함수형 프로그래밍 유틸리티