tobimori / kirby-trawl
Automatic translation extraction for Kirby CMS
Installs: 4
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 0
Forks: 0
Open Issues: 0
Type:kirby-plugin
Requires
- php: >=8.0
- getkirby/composer-installer: ^1.2
- nikic/php-parser: ^4.0 || ^5.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.75
- getkirby/cms: ^5.0
- pestphp/pest: ^2.0
- pestphp/pest-plugin-type-coverage: ^2.0
- phpstan/phpstan: ^1.10
README
Trawl is an experimental Kirby plugin for extracting translation strings from Kirby templates and content files.
It's made to be combined with an AI localization tool like Lingo.dev to automate the process of translating your blueprints and templates.
You can find an example implementation of Trawl + Lingo using GitHub Actions CI/CD in the Baukasten repository.
Setup Guide
1. Install Kirby CLI
composer global require getkirby/cli
Add composer bin directory to your shell profile:
# Find your global composer directory composer -n config --global home # Add to ~/.bash_profile (macOS) or ~/.bashrc (Linux) export PATH=~/.composer/vendor/bin:$PATH
Verify installation:
kirby
2. Install Plugin
composer require tobimori/kirby-trawl
3. Configure
Add to your config.php
:
return [ 'tobimori.trawl' => [ 'sourceLanguage' => 'en', // Source language for extraction (leave empty to output just keys) 'languages' => ['de', 'en'] // Languages to validate ], ];
These config options serve as defaults for the CLI commands. You can override them with command flags when needed. For example, if sourceLanguage
is empty, the extract command will output translation keys without values.
4. Update Language Files
Load translations from JSON files in your language files:
<?php use Kirby\Data\Json; return [ 'code' => 'de', 'default' => true, 'direction' => 'ltr', 'locale' => [ 'LC_ALL' => 'de_DE' ], 'name' => 'Deutsch', 'translations' => Json::read(__DIR__ . '/../translations/de.json'), 'url' => '' ];
5. Extract Translations
Run the extract command to generate translation files:
php kirby trawl:extract --output=site/translations/en.json --format=json
6. Add to CI/CD
Add Trawl to your build process to keep translations in sync. Check the Baukasten repository for a complete GitHub Actions example.
Commands
trawl:extract
- Extract translation strings to JSON/YAML/PHPtrawl:validate
- Check for missing or unused translationstrawl:migrate
- Rename translation keys across your codebase (to what's in your source language file)
What Gets Extracted
- Blueprint fields:
label
,title
,help
,placeholder
,empty
,info
,text
,description
,confirm
- Language variables:
*: translation.key
in options - KQL expressions:
{{ t("key") }}
,{{ tc("key") }}
,{{ tt("key") }}
- PHP functions:
t()
,tc()
,tt()
License
MIT License Copyright © 2025 Tobias Möritz