@sheet-i18n/importer NPM

@sheet-i18n/importer ✨

The server-side importer subpackage allows you to interact with Google Sheets and export translations directly into your project. This is primarily used in server-side environments, such as Next.js API routes or other backend frameworks, where you want to fetch and store translations from a Google Spreadsheet to be served to clients or used within your server application.

import { googleSheetImporter } from 'sheet-i18n/importer';

const importer = await googleSheetImporter({
  credentials: {
    sheetId: 'your-google-sheet-id',
    clientEmail: 'your-client-email',
    privateKey: 'your-private-key',
  },
  defaultLocale: 'default-language-in-sheet-header',
});

await importer.importTranslations();

Configuration ⚙️

The configuration object required for using the importer is as follows:

Required 📝

credentials: Google Sheets API credentials:
- sheetId: The ID of your Google Spreadsheet (extracted from the URL).
- clientEmail: The email of the Google Sheets API client.
- privateKey: The private key associated with the client.
defaultLocale: The default locale/language specified in your Google Sheet header.

Optional 🔧

headerStartRowNumber: Specifies the row number where the headers begin (if not at the top).
ignoredSheets: A list of sheets to exclude by title. By default, sheets without the defaultLocale in headers will be ignored.
importPath: Path to save exported translations from your sheet. This is the location where the exported translations will be saved. By default, it will use the current working directory (cwd). This option is only used when calling the importTranslations method.

Importer Methods 🛠️

`getTranslations` 📝

Description: This function retrieves the translation data, which is structured by locale keys (such as "ko", "en", etc.). It collects all translations from the specified sheet, replaces any placeholders, and prepares them to be sent to the client in the response body. Each key corresponds to a language, and the value for each key is an object containing the translated text for that locale.
Type: Function
Parameters: None
Returns: An object where each key is a locale (e.g., "ko", "en"), and the value is the respective translation data for that locale.

Example:

If the headers in your Google Sheets are ["ko", "en", ...], the result returned by getTranslations will look like this:

{
  "ko": {
    "greeting": "안녕하세요",
    "farewell": "안녕히 가세요"
  },
  "en": {
    "greeting": "Hello",
    "farewell": "Goodbye"
  }

  ...
}

In this example:

"ko" contains the translations for Korean.
"en" contains the translations for English. Each locale’s object contains key-value pairs for individual translations.

`importTranslations` 📤

Description: This asynchronous function is used in a Node.js environment to export translations directly into your project. It is especially useful if your project includes server-side APIs (like Next.js API routes) and you need to update the locale JSON data in your project. It can be invoked to update or create the locale files within your project, ensuring that the translation data is synced with the local environment.
Type: Function
Parameters: None
Returns: void

Example:

If you call the importTranslations function, it will update or create JSON files in your project for each locale. The result could look like this:

// ko.json
{
  "greeting": "안녕하세요",
  "farewell": "안녕히 가세요"
}

// en.json
{
  "greeting": "Hello",
  "farewell": "Goodbye"
}

API Documentation 📚

This package provides a streamlined way to export data using sheets API. It is designed to simplify the integration of spreadsheet data into your applications, particularly for translation workflows and internationalization (i18n).

Google Sheets API Documentation Google Auth Library Google Spreadsheet

Exported Data Format 🗂️

The exported translations will be saved in a format that is easy to use for localization purposes. Each translation is stored in its respective locale folder, with a structured format.