English | 한국어

English

🌐 i18n-spreadsheet-to-json

Provides functionality to parse Google Sheets data and generate and synchronize JSON files. Helps with internationalization (i18n) for applications supporting multiple languages.

Google Sheets 데이터를 파싱하여 JSON 파일을 생성 및 동기화하는 기능을 제공합니다. 여러 언어를 지원하는 애플리케이션을 위한 국제화(i18n)를 도와줍니다.

Features

• Per-language JSON output, one file per locale, nested via dot-notation keys (e.g. auth.login.title).
• Sync all sheets at once, only the sheets you pin in customIncludedSheets, or a single sheet by name.
• Skip rows you don't want shipped: prefix the key with // for comments, or put _N/A in a cell to leave that locale empty.
• Supports spreadsheets with more than 26 languages (columns beyond Z are handled correctly).
• Friendly error if you pass a sheet name that doesn't exist — the CLI lists the available titles.

Requirements

• Node.js >= 18 (uses the built-in fetch).
• A Google Sheets API key with read access to the target spreadsheet (sharing must be at least "Anyone with the link · Viewer").

Installation

npm install @actionpower/i18n-spreadsheet-to-json --save-dev

yarn add @actionpower/i18n-spreadsheet-to-json --dev

Usage

i18nconfig.json

Library configuration is done in the i18nconfig.json file.

Create i18nconfig.json at the root path.

//example
{
  "GOOGLE_API_KEY": "YOUR_GOOGLE_API_KEY",
  "GOOGLE_SHEET_ID": "YOUR_GOOGLE_SHEET_ID",
  "targetDir": "./locales",
  "languages": ["ko", "en", "zh"], //optional
  "customIncludedSheets": ["person", "authPage"] //optional
}

| Variable | Description | Required | Default | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | | GOOGLE_API_KEY | API key for using Google Sheets API. How to get it | required | - | | GOOGLE_SHEET_ID | ID of the Google Sheets document to fetch data from. You can find it in the spreadsheet's URL. docs.google.com/spreadsheets/d/[GOOGLE_SHEET_ID]/edit?usp=sharing | required | - | | targetDir | Directory path where the parsed JSON files will be saved. | required | - | | languages | Array of supported language codes. JSON files corresponding to each language code will be created in targetDir. | optional | ["ko", "en"] | | customIncludedSheets | Use this when you want to manage only specific sheets in a large spreadsheet. | optional | All sheets |

Sheet format

Each sheet (tab) follows the same layout:

| Column | Content | | ------ | ------- | | A | The translation key in dot-notation (e.g. auth.login.title). Nested objects are built from the dots. | | B, C, D, … | One column per language, in the same order as the languages array in your config. |

Special markers:

• Row starts with // → treated as a comment, skipped entirely.
• Cell value is _N/A → that locale stays empty for that key (the other locales still get populated).
• If a key appears more than once, the earlier row wins (later duplicates are ignored).

Execution

npm run i18n

yarn i18n

• Use the above command in the terminal to update all spreadsheets.
• If you have defined customIncludedSheets in your config, only the sheets specified in that array will be updated.

If you have set customIncludedSheets but want to update all sheets in your spreadsheet, use the --all flag:

npm run i18n --all

yarn i18n --all

If you specify a sheet name, only the sheet corresponding to that name will be updated, regardless of customIncludedSheets setting:

npm run i18n [sheetName]

yarn i18n [sheetName]

Example

• Create a spreadsheet.

⚠Ensure that the sharing access permission is set to "Anyone with the link" (Viewer). If it is set to restricted, API requests will not be possible.

• Open the terminal in your project directory and run the yarn i18n [sheetName] command. A JSON file will be created in the targetDir specified in the i18nconfig.json file.

./locales/ko/person.json

{
  "person": {
    "address": "서울특별시 종로구 사직로 161",
    "hobbies": ["독서", "수영", "악기 연주"]
  }
}

./locales/en/person.json

{
  "person": {
    "address": "161 Sajik-ro, Jongno-gu, Seoul, South Korea",
    "hobbies": ["Reading", "Swimming", "Playing an instrument"]
  }
}

./locales/zh/person.json

{
  "person": {
    "address": "韩国首尔特别市鐘路區社稷路161号",
    "hobbies": ["阅读", "游泳", "演奏乐器"]
  }
}

Bug Fixes

[2024/10/14] version 0.0.34

Resolved an issue where updating sheet values in bulk through the i18n command resulted in only two languages being reflected correctly in Google Sheets. Previously, when three or more languages were updated, additional languages would appear as blank values. This bug has now been fixed, ensuring that all specified languages are updated correctly.

한국어

주요 기능

• 로케일별로 JSON 파일을 분리 생성. 키는 점(.) 표기로 중첩 객체를 구성합니다 (예: auth.login.title).
• 전체 시트 / customIncludedSheets로 지정한 시트만 / 특정 시트 하나만 동기화 가능.
• 배포에서 빼고 싶은 행은 키 앞에 //로 주석 처리, 특정 로케일만 비워두고 싶으면 셀에 _N/A 입력.
• 27개 이상의 언어 (스프레드시트 컬럼 Z 너머) 지원.
• 존재하지 않는 시트 이름을 인자로 주면 CLI가 사용 가능한 시트 목록과 함께 친절한 에러 메시지를 보여줍니다.

요구 사항

• Node.js 18 이상 (빌트인 fetch 사용).
• 대상 스프레드시트에 대한 읽기 권한이 있는 Google Sheets API 키 (공유 권한이 최소 "링크가 있는 모든 사용자 · 뷰어"여야 합니다).

설치

npm install @actionpower/i18n-spreadsheet-to-json --save-dev

yarn add @actionpower/i18n-spreadsheet-to-json --dev

사용법

i18nconfig.json

라이브러리 설정은 i18nconfig.json 파일에서 이루어집니다.

루트 경로에 i18nconfig.json을 생성합니다.

//example
{
  "GOOGLE_API_KEY": "YOUR_GOOGLE_API_KEY",
  "GOOGLE_SHEET_ID": "YOUR_GOOGLE_SHEET_ID",
  "targetDir": "./locales",
  "languages": ["ko", "en", "zh"], //optional
  "customIncludedSheets": ["person", "authPage"] //optional
}

| 변수 | 설명 | 필수 여부 | 기본값 | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------ | | GOOGLE_API_KEY | Google Sheets API를 사용하기 위한 API 키입니다. 발급방법 | required | - | | GOOGLE_SHEET_ID | 데이터를 가져올 Google Sheets 문서의 ID입니다. spreadSheets의 url을 통해 ID를 알 수 있습니다. docs.google.com/spreadsheets/d/[GOOGLE_SHEET_ID]/edit?usp=sharing | required | - | | targetDir | 파싱된 JSON 파일이 저장될 디렉토리 경로입니다. | required | - | | languages | 지원하는 언어 코드의 배열입니다. 각 언어 코드에 해당하는 JSON 파일이 targetDir에 생성됩니다. | optional | ["ko", "en"] | | customIncludedSheets | 대규모 스프레드시트에서 특정 시트들만 관리하고 싶을 때 사용하세요. | optional | 전체 시트 |

시트 형식

각 시트(탭)는 동일한 레이아웃을 따릅니다:

| 컬럼 | 내용 | | ---- | ---- | | A | 점(.) 표기 번역 키 (예: auth.login.title). 점을 따라 중첩 객체가 만들어집니다. | | B, C, D, … | 언어별로 한 컬럼. 설정의 languages 배열과 동일한 순서여야 합니다. |

특수 마커:

• 키가 //로 시작 → 주석 처리 행으로 간주, 전체 스킵.
• 셀 값이 _N/A → 해당 키의 그 로케일만 비워둠 (다른 로케일은 정상 채워짐).
• 같은 키가 여러 번 등장하면 먼저 나온 행이 우선 (이후 중복은 무시).

실행

npm run i18n

yarn i18n

• 터미널에서 위 명령어를 이용해 모든 스프레드 시트를 업데이트할 수 있습니다.
• i18nconfig.json에 customIncludedSheets를 정의한 경우, 해당 배열에 지정된 시트만 업데이트됩니다.

customIncludedSheets를 설정했더라도 전체 시트를 모두 업데이트하고 싶다면 --all 플래그를 사용하세요:

npm run i18n --all

yarn i18n --all

특정 시트 이름을 지정하면 customIncludedSheets 설정에 관계없이 해당 이름의 시트만 업데이트됩니다:

npm run i18n [sheetName]

yarn i18n [sheetName]

Example

• 스프레드 시트를 작성합니다.

⚠공유 엑세스 권한이 링크가 있는 모든 사용자(뷰어)로 되어있는지 확인해주세요. 제한됨으로 되어있으면 api 요청이 불가능합니다.

• 프로젝트 경로에서 터미널을 열고 yarn i18n [sheetName] 명령어를 입력하면 i18nconfig.json 파일에 지정한 targetDir 경로에 [sheetName].json파일이 생성됩니다.

./locales/ko/person.json

{
  "person": {
    "address": "서울특별시 종로구 사직로 161",
    "hobbies": ["독서", "수영", "악기 연주"]
  }
}

./locales/en/person.json

{
  "person": {
    "address": "161 Sajik-ro, Jongno-gu, Seoul, South Korea",
    "hobbies": ["Reading", "Swimming", "Playing an instrument"]
  }
}

./locales/zh/person.json

{
  "person": {
    "address": "韩国首尔特别市鐘路區社稷路161号",
    "hobbies": ["阅读", "游泳", "演奏乐器"]
  }
}

버그 수정

[2024/10/14] version 0.0.34

i18n 명령어를 통해 시트 값을 일괄 업데이트할 때 Google Sheets에서 두 개의 언어만 정상적으로 반영되는 문제를 해결했습니다. 이전에는 세 개 이상의 언어를 업데이트할 경우 추가 언어가 빈 값으로 표시되는 버그가 있었습니다. 이 버그가 수정되어 지정한 모든 언어가 올바르게 업데이트됩니다.

License

MIT — see package.json.