📊
Google Sheets 연동
팀 협업을 위해 Google Sheets와 번역을 동기화합니다
개요
Google Sheets 통합을 통해 번역가, 기획자, 개발자가 함께 번역 작업을 할 수 있습니다. 로컬 JSON 파일과 Google Sheets를 양방향으로 동기화할 수 있습니다.
✓팀원들과 실시간 협업
✓비개발자도 쉽게 번역 작업 가능
✓증분 업데이트로 안전한 동기화
✓강제 동기화 옵션 제공
초기 설정
1
Google Cloud 프로젝트 생성
- Google Cloud Console에 접속
- 새 프로젝트 생성 또는 기존 프로젝트 선택
2
Google Sheets API 활성화
- API 및 서비스 > 라이브러리로 이동
- "Google Sheets API" 검색
- 사용 설정 클릭
3
서비스 계정 생성
- API 및 서비스 > 사용자 인증 정보로 이동
- 사용자 인증 정보 만들기 > 서비스 계정 선택
- 서비스 계정 이름 입력 (예: i18n-sync)
- 역할: 편집자 선택
- 완료 클릭
4
인증 정보 JSON 다운로드
- 생성한 서비스 계정 클릭
- 키 탭으로 이동
- 키 추가 > 새 키 만들기
- JSON 유형 선택
- 다운로드된 JSON 파일을 프로젝트 루트에 저장 (예: credentials.json)
⚠️ 주의: credentials.json 파일은 절대 Git에 커밋하지 마세요! .gitignore에 추가하세요.
5
Google Sheets 생성 및 공유
- Google Sheets에서 새 스프레드시트 생성
- URL에서 Spreadsheet ID 복사 (예: 1abc...xyz)
- 공유 버튼 클릭
- 서비스 계정 이메일 추가 (credentials.json의 client_email)
- 편집자 권한 부여
6
설정 파일 업데이트
i18nexus.config.json 파일에 Google Sheets 정보 추가:
{
"languages": ["en", "ko"],
"defaultLanguage": "ko",
"localesDir": "./locales",
"sourcePattern": "app/**/*.{ts,tsx}",
"googleSheets": {
"spreadsheetId": "YOUR_SPREADSHEET_ID",
"credentialsPath": "./credentials.json",
"sheetName": "Translations"
}
}i18n-upload: 로컬에서 Sheets로
로컬 번역 파일을 Google Sheets로 업로드합니다. 기존 Sheets의 데이터는 완전히 대체됩니다.
기본 사용법
npx i18n-upload --spreadsheet-id "YOUR_ID" --credentials "./credentials.json"명령어 옵션
--spreadsheet-idGoogle Sheets의 Spreadsheet ID
--credentials서비스 계정 인증 정보 JSON 파일 경로
--sheet-name시트 이름 (기본값: "Translations")
⚠️주의사항
- •업로드는 Sheets의 기존 데이터를 완전히 대체합니다
- •중요한 Sheets 데이터가 있다면 먼저 백업하세요
- •일반적으로 프로젝트 초기에 한 번만 사용합니다
i18n-download: Sheets에서 로컬로
Google Sheets의 번역을 로컬 파일로 다운로드합니다. 증분 업데이트 방식으로 기존 번역을 보존합니다.
기본 사용법
npx i18n-download --spreadsheet-id "YOUR_ID" --credentials "./credentials.json"작동 방식
- 1.Google Sheets에서 모든 번역을 읽어옴
- 2.로컬 파일의 기존 번역을 읽어옴
- 3.Sheets의 번역으로 업데이트하되, 로컬에만 있는 번역은 보존
- 4.병합된 결과를 로컬 파일에 저장
✓안전한 증분 업데이트
i18n-download는 기존 번역을 보존하면서 Sheets의 변경사항만 가져옵니다:
- ✓Sheets에 있는 키: 값을 업데이트
- ✓로컬에만 있는 키: 그대로 유지
- ✓Sheets에 새로 추가된 키: 로컬에 추가
i18n-download-force: 강제 동기화
Google Sheets의 데이터로 로컬 번역 파일을 완전히 덮어씁니다.
기본 사용법
npx i18n-download-force --spreadsheet-id "YOUR_ID" --credentials "./credentials.json"일반 download와 차이점
i18n-download
- •증분 업데이트
- •로컬 번역 보존
- •안전함
i18n-download-force
- •전체 덮어쓰기
- •로컬 번역 삭제
- •주의 필요
⚠️경고
- •이 명령어는 로컬 번역 파일을 완전히 덮어씁니다
- •로컬에만 있는 번역이 모두 삭제됩니다
- •Sheets를 단일 진실 공급원(Single Source of Truth)로 사용할 때만 사용하세요
워크플로우 예제
초기 설정 및 업로드
# 1. 코드에서 번역 키 추출
npx i18n-extractor -p "app/**/*.tsx" -d "./locales"
# 2. 로컬 번역을 Google Sheets로 업로드
npx i18n-upload --spreadsheet-id "YOUR_ID"
# 3. 팀원들이 Google Sheets에서 번역 작업 시작일상적인 동기화
# 1. 개발자: 새로운 기능 추가 후 키 추출
npx i18n-extractor
# 2. 개발자: 새 키를 Sheets에 업로드
npx i18n-upload --spreadsheet-id "YOUR_ID"
# 3. 번역가: Google Sheets에서 번역 작업
# 4. 개발자: 번역 완료 후 로컬로 다운로드
npx i18n-download --spreadsheet-id "YOUR_ID"
# 5. Git에 변경사항 커밋
git add locales/
git commit -m "Update translations"CI/CD 통합
# .github/workflows/sync-translations.yml
name: Sync Translations
on:
schedule:
- cron: '0 2 * * *' # 매일 오전 2시
workflow_dispatch: # 수동 실행 가능
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Download translations
run: |
npx i18n-download \\
--spreadsheet-id "\${{ secrets.SHEET_ID }}" \\
--credentials ./credentials.json
- name: Create PR if changes
uses: peter-evans/create-pull-request@v5
with:
title: "Update translations from Sheets"
commit-message: "chore: sync translations"모범 사례
✅증분 다운로드 우선 사용
대부분의 경우 i18n-download를 사용하세요. 안전하게 변경사항만 가져옵니다.
✅인증 정보 안전하게 관리
credentials.json을 .gitignore에 추가하고 환경 변수나 시크릿으로 관리하세요.
# .gitignore
credentials.json
*.credentials.json✅Sheets 구조 유지
Google Sheets의 첫 행은 언어 코드여야 하며, 첫 열은 번역 키여야 합니다. 이 구조를 변경하지 마세요.
💡정기적인 동기화
주기적으로 동기화하여 번역이 최신 상태로 유지되도록 하세요.
문제 해결
오류: 권한이 없습니다
해결 방법:
- Google Sheets가 서비스 계정 이메일과 공유되었는지 확인
- 편집자 권한이 부여되었는지 확인
오류: API가 활성화되지 않음
해결 방법:
- Google Cloud Console에서 Google Sheets API가 활성화되었는지 확인
- 올바른 프로젝트를 선택했는지 확인
오류: 인증 정보를 찾을 수 없음
해결 방법:
- credentials.json 파일이 올바른 경로에 있는지 확인
- 파일 경로를 절대 경로로 시도