i18n-po-sheet-sync/dist/index.d.mts

A Node.js library that facilitates synchronization between multilingual PO files and Google Spreadsheets.

import { JWTOptions } from "google-auth-library";
import { GoogleSpreadsheetRow } from "google-spreadsheet";
import pofile from "pofile";

//#region src/types.d.ts
type Language = string;
type ServiceAccount = Omit<JWTOptions, 'scopes'>;
interface RGBColor {
  r: number;
  g: number;
  b: number;
}
interface I18nSyncConfig {
  /**
   * Service account credentials (required)
   * @example {
   *   email: serviceAccount.client_email,
   *   key: serviceAccount.private_key,
   * }
   */
  serviceAccount: ServiceAccount;
  /**
   * Spreadsheet ID (required)
   */
  spreadsheetId: string;
  /**
   * Languages (required)
   * @example ['en', 'ko', 'ja']
   */
  languages: Language[];
  /**
   * Base path for PO files (required)
   * @example join(__dirname, 'locales')
   */
  poFilesBasePath: string;
  /**
   * Sheet index (optional)
   */
  sheetIndex?: number;
}
interface HeaderMapping {
  msgid: string;
  msgctxt?: string;
  references?: string;
  comments?: string;
  extractedComments?: string;
}
type HeaderMappingValue = NonNullable<HeaderMapping[keyof HeaderMapping]>;
type Row = Record<HeaderMappingValue, string>;
type SheetRow = GoogleSpreadsheetRow<Row>;
type POItem = InstanceType<typeof pofile.Item>;
interface ExportOptions {
  /**
   * Filter out missing translations
   * @default false
   */
  filterMissingTranslations?: boolean;
  /**
   * Preserve existing items
   * @default false
   */
  preserveExistingItems?: boolean;
  /**
   * Plural forms by language
   * @default {
   *   ko: "nplurals=1; plural=0;",
   *   en: "nplurals=2; plural=(n != 1);",
   * }
   */
  pluralFormsByLanguage?: Record<Language, string>;
}
interface UploadOptions {
  /**
   * Apply conditional formatting to empty translation cells
   * @default true
   */
  applyConditionalFormatting?: boolean;
  /**
   * Background color for empty cells (HEX code)
   * @default "#FFEBEE"
   */
  emptyColor?: string;
  /**
   * Preserve existing translations
   */
  preserveExistingTranslations?: boolean;
}
interface ExportResult {
  language: Language;
  totalItems: number;
  updatedItems: number;
  removedItems: number;
  filePath: string;
}
interface UploadResult {
  language?: Language;
  totalItems: number;
  addedItems: number;
  updatedItems: number;
  status?: 'success' | 'failed';
}
//#endregion
//#region src/index.d.ts
declare class I18nPOSheetSync {
  private config;
  private headerMapping;
  constructor(config: I18nSyncConfig, headerMapping?: HeaderMapping);
  /**
   * Export data from Google Spreadsheet to PO files
   * @param options Export options
   */
  exportToPO(options?: ExportOptions): Promise<ExportResult[]>;
  /**
   * Upload data from PO files to Google Spreadsheet (Bulk update after sheet reset)
   * @param options Upload options
   */
  uploadFromPO(options?: UploadOptions): Promise<UploadResult>;
  /**
   * Apply conditional formatting to empty translation cells
   * @param emptyColor Background color for empty cells (HEX code)
   */
  applyConditionalFormatting(emptyColor?: string): Promise<void>;
}
//#endregion
export { ExportOptions, ExportResult, HeaderMapping, I18nSyncConfig, Language, POItem, RGBColor, Row, ServiceAccount, SheetRow, UploadOptions, UploadResult, I18nPOSheetSync as default };