PHPackages                             timber/wp-i18n-twig - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. timber/wp-i18n-twig

ActiveWp-cli-package[Templating & Views](/categories/templating)

timber/wp-i18n-twig
===================

WordPress translations extraction for Twig files with WP-CLI

v1.1.0(5mo ago)1254.2k↓33.8%1PHPCI passing

Since Jan 18Pushed 5mo ago2 watchersCompare

[ Source](https://github.com/timber/wp-i18n-twig)[ Packagist](https://packagist.org/packages/timber/wp-i18n-twig)[ GitHub Sponsors](https://github.com/timber)[ Fund](https://opencollective.com/timber)[ RSS](/packages/timber-wp-i18n-twig/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (4)Versions (4)Used By (0)

wp-i18n-twig
============

[](#wp-i18n-twig)

[![tests](https://github.com/timber/wp-i18n-twig/actions/workflows/testing.yml/badge.svg)](https://github.com/timber/wp-i18n-twig/actions/workflows/testing.yml)

Parsing WordPress translations in Twig/Timber templates has always been quirky and not very convenient. Especially since WordPress started grabbing translations from multiple sources (theme stylesheet, {block,theme}.json, block editor JS, PHP files) and now also outputing in multiple formats (po, [php](https://make.wordpress.org/core/2024/02/27/i18n-improvements-6-5-performant-translations/)).

WP-CLI being the recommended way to create/update POT files, `timber/wp-i18n-twig` provides (almost native) Twig translation extraction by overriding the default `wp i18n make-pot`.

Install
-------

[](#install)

Because WP-CLI default commands are not meant to be overridden, there are two working ways to install `timber/wp-i18n-twig`:

### Global

[](#global)

If you want to use it with a global installed `wp` (`/usr/local/bin/wp` or similar), you have to install it as a WP-CLI package:

```
wp package install timber/wp-i18n-twig
```

### Local

[](#local)

You can also install the package at the project level using composer and run WP-CLI from the local `vendor/bin/wp`:

```
composer require timber/wp-i18n-twig
```

Usage
-----

[](#usage)

Usage is the same than `wp i18n make-pot` command.

```
wp i18n make-pot /path/to/my/theme languages/my-theme.pot
```

`--debug` flag is handy if you want to check the templates that have been parsed (and watch for parsing errors):

```
wp i18n make-pot /path/to/my/theme languages/my-theme.pot --debug
```

Please refer to the [`wp i18n` command documentation](https://developer.wordpress.org/cli/commands/i18n/) for more detailed information.

To match `wp i18n make-pot` behavior, a `--skip-twig` flag has been added in case skipping Twig files extraction is needed.

Translations
------------

[](#translations)

`timber/wp-i18n-twig` handles the [same translations functions and feature scope](features/makepot.feature) `wp i18n` does.

It does also support translators comments, at [an evil cost](/src/Utils/TwigFunctionsScanner.php#L29-L39).

Adding translators comments in your Twig templates works like it would in PHP, place it on the same line or the line before the translation string:

```
{# translators: Translators 1! #}
{{ __( 'hello world', 'foo-theme' ) }}

{# Translators: Translators 2! #}
{{ __( 'foo', 'foo-theme' ) }}

{# translators: this should get extracted. #} {{ __( 'baba', 'foo-theme' ) }}

{# translators: boo #} {# translators: this should get extracted too. #} {# some other comment #} {{__( 'bubu', 'foo-theme' ) }}
```

Custom tags
-----------

[](#custom-tags)

When working with Twig, you may require popular Twig libraries that register custom tags (such as `{% dump %}`, `{% cache %}`, etc.). `timber/wp-i18n-twig` will automatically load the token parsers for the following tags:

- Tags from [symfony/twig-brigde](https://github.com/symfony/twig-bridge):
    - `{% dump %}`
    - `{% form_theme %}`
    - `{% stopwatch %}`
    - `{% trans_default_domain %}`
    - `{% trans %}`
- Tags from [twigphp/cache-extra](https://github.com/twigphp/cache-extra):
    - `{% cache %}`
- Tags from [symfony/ux](https://github.com/symfony/ux)
    - `{% component %}`
    - `{% props %}`

Important

For the token parsers to be loaded, you must use the local version of `timber/wp-i18n-twig` (`vendor/bin/wp`).

Limitations
-----------

[](#limitations)

To make this package work in any Twig environment, templates are not compiled to PHP but only parsed. This main benefit is that it's (almost) configuration agnostic (custom filters, functions, template location).

However, since Twig is highly configurable, there are still some (minor) limitations.

- Custom tags other than the supported ones above will result in parsing errors.
- Using [non default block/comment/variable tags](https://github.com/twigphp/Twig/blob/4c179c8a64fece77e17ef299d1a2a3f908993107/src/Lexer.php#L58-L64) isn't supported and probably won't ever be.

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance70

Regular maintenance activity

Popularity37

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 87.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~339 days

Total

3

Last Release

171d ago

Major Versions

0.1.0 → v1.0.02024-04-25

### Community

Maintainers

![](https://www.gravatar.com/avatar/692aa0b61ab3442df442597fb9526c13d82252ec3836c574edab4a0b9b38dc38?d=identicon)[jarednova](/maintainers/jarednova)

![](https://www.gravatar.com/avatar/62f16c9d375343e12eb02b2a3095dc9a02047287b5f12f75ef4c59929fcb2802?d=identicon)[n5s](/maintainers/n5s)

![](https://avatars.githubusercontent.com/u/2084481?v=4)[Lukas Gächter](/maintainers/gchtr)[@gchtr](https://github.com/gchtr)

![](https://www.gravatar.com/avatar/45358b482bc8b484db0de4b5b8699071edce2808939b5f3ffdf88568355c4c2b?d=identicon)[levdbas](/maintainers/levdbas)

---

Top Contributors

[![nlemoine](https://avatars.githubusercontent.com/u/2526939?v=4)](https://github.com/nlemoine "nlemoine (21 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")[![szepeviktor](https://avatars.githubusercontent.com/u/952007?v=4)](https://github.com/szepeviktor "szepeviktor (1 commits)")

---

Tags

i18ntwigwordpresswp-cli

### Embed Badge

![Health badge](/badges/timber-wp-i18n-twig/health.svg)

```
[![Health](https://phpackages.com/badges/timber-wp-i18n-twig/health.svg)](https://phpackages.com/packages/timber-wp-i18n-twig)
```

###  Alternatives

[twig/extra-bundle

A Symfony bundle for extra Twig extensions

91492.0M315](/packages/twig-extra-bundle)[twig/intl-extra

A Twig extension for Intl

36763.2M221](/packages/twig-intl-extra)[rcrowe/twigbridge

Adds the power of Twig to Laravel

9105.9M50](/packages/rcrowe-twigbridge)[twig/string-extra

A Twig extension for Symfony String

22046.0M133](/packages/twig-string-extra)[twig/cssinliner-extra

A Twig extension to allow inlining CSS

22918.5M55](/packages/twig-cssinliner-extra)[symfony/ux-twig-component

Twig components for Symfony

21914.8M162](/packages/symfony-ux-twig-component)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)