Translate Vue 3 applications with gettext.

Install

npm i @rareformlabs/vue3-gettext

Basic usage

In templates:

<span>
  {{ $gettext("I'm %{age} years old!", { age: 32 }) }}
</span>

In code:

const { $gettext } = useGettext();

console.log($gettext("Hello World!"));

Features

• simple, ergonomic API
• reactive translations in Vue templates and TypeScript/JavaScript code
• CLI to automatically extract messages from code files
• AI-assisted PO translation for missing entries
• support for pluralization and message contexts

Extraction, Translation & Configuration

This fork includes improved extraction tools with configurable location comments, auto-filling support, and optional AI-assisted translation.

Create a gettext.config.js in your project root:

export default {
  input: {
    path: "./src",
    include: ["**/*.js", "**/*.ts", "**/*.vue"],
    exclude: [],
  },
  output: {
    path: "./src/language",
    locales: ["en", "es"],
    /**
     * "full": file and line number (default)
     * "file": filename only (reduces merge conflicts)
     * "never": no location comments
     */
    addLocation: "file",
    /**
     * If true, empty msgstr entries in PO files will be filled with the msgid.
     * Can also be an array of locales to auto-fill (e.g. ["en"]).
     * Useful for mechanical default locales (e.g. English).
     */
    autoFill: ["en"],
  },
  translate: {
    provider: "openai",
    model: "gpt-4.1-mini", // default translation model
    // optional: limit translation to specific locales instead of output.locales
    locales: ["es"],
    // default false: only fill missing entries; true means retranslate existing msgstr values too
    includeTranslated: false,
    openai: {
      /**
       * Default: "api-key"
       * - "api-key" uses https://api.openai.com/v1/chat/completions
       * - "oauth" uses ChatGPT/Codex OAuth via @mariozechner/pi-ai and https://chatgpt.com/backend-api/codex/responses
       */
      authMode: "api-key",
      // optional override, defaults to OPENAI_API_KEY
      apiKeyEnvVar: "OPENAI_API_KEY",
      // advanced: override the API base URL; normally leave unset
      baseUrl: undefined,
    },
  },
};

OAuth mode example:

export default {
  translate: {
    provider: "openai",
    model: "gpt-5.4",
    includeTranslated: false,
    openai: {
      authMode: "oauth",
      // where vue-gettext reads/writes saved OAuth credentials
      // defaults to ~/.vue-gettext/openai-codex-oauth.json
      credentialsPath: "./.gettext/openai-codex-oauth.json",
      // SECURITY WARNING: Do not commit OAuth credentials to version control!
      // 1. Add credentialsPath to .gitignore (e.g., echo ".gettext/" >> .gitignore)
      // 2. Restrict file permissions (e.g., chmod 600 ./.gettext/openai-codex-oauth.json)
      // 3. Consider using env var overrides below to avoid storing tokens on disk
      // optional env overrides if you do not want a file
      accessTokenEnvVar: "OPENAI_OAUTH_ACCESS_TOKEN",
      refreshTokenEnvVar: "OPENAI_OAUTH_REFRESH_TOKEN",
      accountIdEnvVar: "OPENAI_OAUTH_ACCOUNT_ID",
      // if a refresh occurs, save the updated credentials back to credentialsPath
      persistRefresh: true,
      // advanced: override the backend endpoint; normally leave unset
      baseUrl: undefined,
      // advanced: override the OAuth originator header only if your environment needs it
      originator: undefined,
    },
  },
};

Credential file formats accepted in OAuth mode:

SECURITY WARNING: Do not commit OAuth credentials to version control!

• Add the credentials file to .gitignore (e.g., echo ".gettext/" >> .gitignore)
• Restrict file permissions (e.g., chmod 600 ./.gettext/openai-codex-oauth.json)
• Alternative: Use environment variable overrides (accessTokenEnvVar, refreshTokenEnvVar, accountIdEnvVar) to avoid storing tokens on disk

{
  "access": "<token>",
  "refresh": "<token>",
  "expires": 1760000000000,
  "accountId": "user-123"
}

or:

{
  "openai-codex": {
    "access": "<token>",
    "refresh": "<token>",
    "expires": 1760000000000,
    "accountId": "user-123"
  }
}

Run extraction:

npx vue-gettext-extract

Run AI translation for missing entries with API key auth:

OPENAI_API_KEY=your-key npx vue-gettext-translate

Run AI translation with OAuth auth:

OPENAI_OAUTH_ACCESS_TOKEN=... \
OPENAI_OAUTH_REFRESH_TOKEN=... \
OPENAI_OAUTH_ACCOUNT_ID=... \
npx vue-gettext-translate

Or point translate.openai.credentialsPath at a saved OAuth JSON file.

Login helper for OAuth:

npx vue-gettext-openai-login

Run compilation:

npx vue-gettext-compile

Contribute

Note: We're publishing a stable 4.1.1 next (dropping the beta suffix).

Please make sure your code is properly formatted (the project contains a prettier config) and all the tests run successfully (npm run test) when opening a pull request.

Please specify clearly what you changed and why.

Credits

This plugin relies heavily on the work of the original vue-gettext.

License

MIT