babel-plugin-ttag

1.8.16 verified Sat Apr 25 auth: no javascript

babel-plugin-ttag (formerly babel-plugin-c-3po) is a Babel plugin for extracting and resolving gettext-like translations at compile time. Current stable version is 1.8.16, released periodically. It uses ES6 tagged template literals (e.g., t`hello`), works with GNU gettext .po files, and offers compile-time resolution with no runtime overhead in the browser. Key differentiators: native template syntax (no sprintf), intelligent extraction by Babel, fast feedback loop (warns on missing translations), and support for universal apps (Node.js and browser). It includes support for plurals (ngettext/msgid), contexts (tct), and JSX without additional configuration. Requires ttag runtime package as a peer dependency.

Common errors

error Error: Could not find module 'ttag' ↓

cause The runtime package 'ttag' is not installed or not in node_modules.

fix

Run 'npm install --save ttag' to install the runtime dependency.

error BabelError: Cannot find module 'babel-plugin-ttag' from ... ↓

cause The plugin is not installed or Babel cannot resolve it.

fix

Run 'npm install --save-dev babel-plugin-ttag' and ensure your Babel config is correct.

error SyntaxError: Unexpected token (or similar parsing error) when using template literal with translation ↓

cause The template literal uses a tag function (e.g., t) but the plugin is not enabled or configured.

fix

Add 'babel-plugin-ttag' to your Babel plugins array and ensure Babel is processing the file.

Warnings

breaking Prior to version 1.0, the package was named babel-plugin-c-3po. The API and configuration may differ. Existing code using 'babel-plugin-c-3po' will not work with 'babel-plugin-ttag' without adjustments. ↓

fix Update package references and configuration to use 'babel-plugin-ttag' and ensure the runtime package 'ttag' is installed.

deprecated Usage of 'c-3po' as a plugin name is deprecated and not supported in this version. ↓

fix Use 'babel-plugin-ttag' instead of 'c-3po' in your Babel configuration.

gotcha The plugin extracts tagged template literals with the tag 't' only. If you alias or rename the import, extraction may fail unless you configure custom tags. ↓

fix Use the default 't' tag or configure custom tags via plugin options (e.g., { functions: ['t', 'myTag'] }).

gotcha Translations file must be in JSON format (e.g., from 'ttag po2json'). Using .po or .pot directly will not work for runtime resolution. ↓

fix Convert .po files to JSON using 'npx ttag po2json translations.po -o translations.json' before passing to the plugin.

Install

npm install babel-plugin-ttag

yarn add babel-plugin-ttag

pnpm add babel-plugin-ttag

Imports

wrong

import t from 'ttag'

correct

import { t } from 'ttag'

t is a named export, not default.

ngettext

wrong

import { ngettext } from 'babel-plugin-ttag'

correct

import { ngettext, msgid } from 'ttag'

ngettext is from the runtime package 'ttag', not the plugin.

tct
wrong
```
import tct from 'ttag'
```
correct
```
import { tct } from 'ttag'
```
tct is a named export for context translation.
BabelPluginTtag (plugin configuration)
wrong
```
{
  plugins: ['ttag']
}
```
correct
```
{
  plugins: ['babel-plugin-ttag']
}
```
Plugin name must be exactly 'babel-plugin-ttag' in .babelrc or babel config.

Quickstart

Installation, basic usage with t and ngettext, plus extraction and compilation commands.

npm install --save-dev babel-plugin-ttag && npm install --save ttag

// .babelrc
{
  "plugins": ["babel-plugin-ttag"]
}

// src/index.js
import { t, ngettext, msgid } from 'ttag';

const name = 'World';
console.log(t`Hello ${name}!`);

const count = 5;
console.log(ngettext(msgid`${count} item`, `${count} items`, count));

// Extract translations: npx ttag extract src/**/*.js -o translations.pot
// Compile translations: npx ttag po2json translations.po -o translations.json
// Then configure plugin to use translations:
// "plugins": [["babel-plugin-ttag", { "translations": "translations.json" }]]