🔄 @atriniumsoft/tm-sync

CLI and library to sync Lingui .po translation files with Translation Manager.

• ⬆️ push — Upload local .po files to Translation Manager
• ⬇️ pull — Download translated .po files from Translation Manager

📦 Installation

npm install @atriniumsoft/tm-sync

Requirements: Node.js >= 18, a Translation Manager instance with API access, and a Lingui project with .po catalogs.

⚙️ Configuration

Set the following environment variables (via .env, .env.local, or system environment):

| Variable | Required | Description | |---|---|---| | TM_API_URL | ✅ | Translation Manager API URL | | TM_API_TOKEN | ✅ | Personal access token (create at Translation Manager > API Tokens) | | TM_PROJECT_SLUG | ✅ | Project slug to sync with | | TM_CATALOGS_DIR | ❌ | Path to Lingui catalogs (default: ./src/locales) |

The CLI automatically loads .env and .env.local files from the current working directory.

🚀 CLI Usage

tm-sync push          # Push all locales
tm-sync push es       # Push a specific locale
tm-sync pull          # Pull all locales
tm-sync pull en       # Pull a specific locale
tm-sync help          # Show help

📝 Recommended npm scripts

{
  "scripts": {
    "tm:push": "tm-sync push",
    "tm:pull": "tm-sync pull && lingui compile --typescript",
    "tm:sync": "lingui extract --overwrite && tm-sync push && tm-sync pull && lingui compile --typescript"
  }
}

Pass a locale as argument: npm run tm:push -- es

🧩 Programmatic API

import { loadConfig, push, pull, createLogger } from "@atriniumsoft/tm-sync";

const config = loadConfig({
  apiUrl: "https://tm.example.com",
  apiToken: "your-token",
  projectSlug: "my-project",
  catalogsDir: "./src/locales",
});

const logger = createLogger(); // or createLogger({ silent: true })

await push(config, logger);           // Push all locales
await pull(config, logger, "es");     // Pull a specific locale

🏷️ Exported types

import type {
  TmSyncConfig,
  TmSyncConfigOverrides,
  PushResult,
  PullResult,
  LocalePushResult,
  LocalePullResult,
  Logger,
  LoggerOptions,
} from "@atriniumsoft/tm-sync";

📄 License

MIT — Atrinium Software