poeditor-sync-tool

CLI tool to export and import translations from POEditor projects.

This utility helps synchronize localization strings between your codebase and POEditor. Use it to extract messages from source files and update .json translations from your POEditor project.

🧩 Available Commands

export-messages

This tool scans your source code for translatable strings and generates a .pot-like file suitable for localization workflows.

npx export-messages --path=./src --out=messages.pot

📝 Arguments

| Flag | Description | Required | Default | | -------- | ----------------------------------------- | -------- | --------------------------------- | | --path | Directory containing source files to scan | ✅ Yes | – | | --out | Path to the output .pot file | ❌ No | messages.pot in the current dir | | --help | Show help text and usage info | ❌ No | – |

📦 What It Extracts

This tool recognizes both function calls and JSX components used for localization.

// Function calls
i18n("You have unread notifications");
i18n("%1 sent a message to %2").arg(senderName, recipientName);

// JSX components
<I18n sentence="Welcome back!" />;
<I18n sentence="%1 uploaded a new file" args={[userName]} />;
<I18n sentence="%1 and %2 joined the meeting" args={["Alice", "Bob"]} />;

Supports both simple strings and argument-based plural/context messages.

💡 Examples

# Extract to a custom output file
npx export-messages --path=./src --out=locales/messages.pot

# Use default output file name
npx export-messages --path=./src

# Show CLI help
npx export-messages --help

import-translations

Synchronizes .json translation files by downloading the latest strings from your POEditor project.

import-translations --dir=translations

Each .json file in the provided directory will be updated based on the associated language code in its filename (uk-UA.json → uk).

💡 Examples

ls -la translations
.
..
uk-UA.json
es-ES.json

In this example:

• uk-UA.json will sync with the uk language in POEditor
• es-ES.json will sync with the es language

🌍 Environment Variables

Create a .env.local file (or define these in your CI/terminal):

POEDITOR_PROJECT_ID=your_project_id_here
POEDITOR_API_TOKEN=your_read_only_token_here

• 🆔 POEDITOR_PROJECT_ID: Your POEditor project ID
• 🔑 POEDITOR_API_TOKEN: A read-only API token (generate it here)

💡 Tip: Add .env.local to your .gitignore to keep credentials secure in version control.