@el-j/google-sheet-translations 1.3.2 → 1.4.0

package/README.md

@@ -11,7 +11,7 @@ A Node.js package for managing translations stored in Google Sheets.
 - ✅ **Modular Architecture**: Well-tested, maintainable codebase with clear separation of concerns
 - ✅ **Next.js Integration**: Built-in support for Next.js static export workflows
 - ✅ **Flexible Configuration**: Customizable paths, wait times, and processing options
-- ✅ **GitHub Action**: One-step CI integration via the bundled composite action
+- ✅ **GitHub Action**: One-step CI integration via `el-j/google-sheet-translations@v2` — see [GitHub Action](#github-action)
 
 ## Installation
 
@@ -290,96 +290,99 @@ For more detailed examples, check out the [examples directory](examples) where y
 This repository ships a composite GitHub Action that lets you fetch translations
 in any workflow **without writing any Node.js scripts yourself**.
 
-### Quick start
+### Quick Start
 
 Add the following step to your workflow after checking out your repository:
 
 ```yaml
 - name: Fetch translations
-  uses: el-j/google-sheet-translations@v1   # pin to a specific release tag for stability
+  uses: el-j/google-sheet-translations@v2
   with:
-    google-client-email:   ${{ secrets.GOOGLE_CLIENT_EMAIL }}
-    google-private-key:    ${{ secrets.GOOGLE_PRIVATE_KEY }}
+    google-client-email: ${{ secrets.GOOGLE_CLIENT_EMAIL }}
+    google-private-key: ${{ secrets.GOOGLE_PRIVATE_KEY }}
     google-spreadsheet-id: ${{ secrets.GOOGLE_SPREADSHEET_ID }}
-    sheet-titles: 'landingPage,about'       # comma-separated sheet tab names
+    sheet-titles: 'home,about,pricing'
 ```
 
-### Inputs
+### Required Secrets
 
-| Input | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `google-client-email` | ✅ | — | Service-account e-mail (`GOOGLE_CLIENT_EMAIL`) |
-| `google-private-key` | ✅ | — | Service-account private key (`GOOGLE_PRIVATE_KEY`) |
-| `google-spreadsheet-id` | ✅ | — | Spreadsheet ID from the sheet URL (`GOOGLE_SPREADSHEET_ID`) |
-| `sheet-titles` | ✅ | — | Comma-separated list of sheet tab names to process |
-| `row-limit` | ❌ | `100` | Maximum rows to read per sheet |
-| `wait-seconds` | ❌ | `1` | Base back-off delay in seconds for retrying rate-limited API calls (HTTP 429/503) |
-| `translations-output-dir` | ❌ | `translations` | Directory for per-locale JSON files |
-| `locales-output-path` | ❌ | `src/i18n/locales.ts` | Path for the generated `locales.ts` |
-| `data-json-path` | ❌ | `src/lib/languageData.json` | Path for the `languageData.json` snapshot |
-| `sync-local-changes` | ❌ | `true` | Push local changes back to the sheet before fetching |
-| `node-version` | ❌ | `20` | Node.js version used to run the fetch script |
-| `package-version` | ❌ | `latest` | Version of `@el-j/google-sheet-translations` to install |
-
-### Outputs
+Store these as [encrypted repository secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) before using the action:
 
-| Output | Description |
+| Secret | Description |
 |--------|-------------|
-| `translations-dir` | Absolute path of the directory containing locale JSON files |
-| `locales-file` | Absolute path of the generated `locales.ts` |
-| `data-json-file` | Absolute path of the `languageData.json` snapshot |
+| `GOOGLE_CLIENT_EMAIL` | Service-account e-mail from your Google Cloud credentials JSON |
+| `GOOGLE_PRIVATE_KEY` | Private key from your Google Cloud credentials JSON (include the full PEM block) |
+| `GOOGLE_SPREADSHEET_ID` | The long ID found in the spreadsheet URL: `…/spreadsheets/d/<ID>/edit` (can be left empty to trigger auto-create) |
 
-### Full workflow example
+### Complete Example
 
-```yaml
-name: Update Translations
+Full workflow that fetches translations on a schedule and commits the results:
 
+```yaml
+name: Sync Translations
 on:
   schedule:
     - cron: '0 6 * * 1'   # every Monday at 06:00 UTC
   workflow_dispatch:
 
 jobs:
-  update-translations:
+  sync:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
       - name: Fetch translations
         id: translations
-        uses: el-j/google-sheet-translations@v1
+        uses: el-j/google-sheet-translations@v2
         with:
-          google-client-email:   ${{ secrets.GOOGLE_CLIENT_EMAIL }}
-          google-private-key:    ${{ secrets.GOOGLE_PRIVATE_KEY }}
+          google-client-email: ${{ secrets.GOOGLE_CLIENT_EMAIL }}
+          google-private-key: ${{ secrets.GOOGLE_PRIVATE_KEY }}
           google-spreadsheet-id: ${{ secrets.GOOGLE_SPREADSHEET_ID }}
-          sheet-titles:          'landingPage,about'
+          sheet-titles: 'home,about,pricing'
           translations-output-dir: 'src/translations'
-          locales-output-path:     'src/i18n/locales.ts'
-          data-json-path:          'src/lib/languageData.json'
+          locales-output-path: 'src/i18n/locales.ts'
+          data-json-path: 'src/lib/languageData.json'
+          sync-local-changes: 'true'
 
       - name: Commit updated translations
-        uses: stefanzweifel/git-auto-commit-action@v5
-        with:
-          commit_message: 'chore(i18n): update translations from Google Sheets'
-          file_pattern: |
-            ${{ steps.translations.outputs.translations-dir }}/**
-            ${{ steps.translations.outputs.locales-file }}
-            ${{ steps.translations.outputs.data-json-file }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add src/translations src/i18n/locales.ts src/lib/languageData.json
+          git diff --staged --quiet || git commit -m "chore(i18n): sync translations from Google Sheets [skip ci]"
+          git push
 ```
 
-### Required secrets
+### All Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `google-client-email` | ✅ | — | Service-account e-mail (`GOOGLE_CLIENT_EMAIL`) |
+| `google-private-key` | ✅ | — | Service-account private key (`GOOGLE_PRIVATE_KEY`) |
+| `google-spreadsheet-id` | ❌ | `''` | Spreadsheet ID from the sheet URL; if empty and `auto-create` is `true`, a new spreadsheet is auto-created |
+| `sheet-titles` | ✅ | — | Comma-separated list of sheet tab names to process (`i18n` is always auto-included) |
+| `row-limit` | ❌ | `100` | Maximum rows to read per sheet |
+| `wait-seconds` | ❌ | `1` | Base back-off delay in seconds for retrying rate-limited API calls (HTTP 429/503) |
+| `translations-output-dir` | ❌ | `translations` | Directory for per-locale JSON files |
+| `locales-output-path` | ❌ | `src/i18n/locales.ts` | Path for the generated `locales.ts` |
+| `data-json-path` | ❌ | `src/lib/languageData.json` | Path for the `languageData.json` snapshot |
+| `sync-local-changes` | ❌ | `true` | Push local changes back to the sheet before fetching |
+| `auto-create` | ❌ | `true` | Automatically create a new spreadsheet when `google-spreadsheet-id` is empty |
+| `spreadsheet-title` | ❌ | `google-sheet-translations` | Title for the auto-created spreadsheet |
+| `source-locale` | ❌ | `en` | Source locale used as the base for auto-translate formulas |
+| `target-locales` | ❌ | `de,fr,es,it,pt,ja,zh` | Comma-separated target locales added to the auto-created spreadsheet |
 
-Store these as [encrypted repository secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets):
+### Outputs
 
-| Secret | Description |
+| Output | Description |
 |--------|-------------|
-| `GOOGLE_CLIENT_EMAIL` | Service-account e-mail from your Google Cloud credentials JSON |
-| `GOOGLE_PRIVATE_KEY` | Private key from your Google Cloud credentials JSON (include the full PEM block) |
-| `GOOGLE_SPREADSHEET_ID` | The long ID found in the spreadsheet URL: `…/spreadsheets/d/<ID>/edit` |
+| `translations-dir` | Absolute path of the directory containing locale JSON files |
+| `locales-file` | Absolute path of the generated `locales.ts` |
+| `data-json-file` | Absolute path of the `languageData.json` snapshot |
+
+### Auto-Create Feature
+
+If `google-spreadsheet-id` is left empty and `auto-create` is `true` (the default), the action will automatically create a new Google Spreadsheet using your service-account credentials. The spreadsheet is pre-populated with an `i18n` starter sheet containing `GOOGLETRANSLATE` formulas for every locale listed in `target-locales`. The new spreadsheet ID is printed to the workflow log and written to your `.env` file (if one exists in the repository root), allowing you to commit it and reuse it in future runs.
 
 ## License
 

package/dist/action-entrypoint.d.ts

@@ -0,0 +1,2 @@
+export declare function run(): Promise<void>;
+//# sourceMappingURL=action-entrypoint.d.ts.map

package/dist/action-entrypoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-entrypoint.d.ts","sourceRoot":"","sources":["../src/action-entrypoint.ts"],"names":[],"mappings":"AAKA,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA4DzC"}