README

A CakePHP plugin for managing translations DB driven.

This branch is for use with CakePHP 5.1+. For details see version map.

Key features

Import from POT, PO files or any service/API.
Web-based and without external dependencies.
Translate strings in all languages simultaneously.
Allow others to help translating without having to know technical details.
Auto-Translate and Auto-Suggest with Translate APIs (e.g. Google Translate PHP/JS, Yandex, ...) for efficiency.
Run i18n extract directly from web interface (with dry run support).
Multi-project support with project-specific locale paths.
Translation coverage dashboard with progress tracking.
PO/POT file analyzer for detecting issues.
TranslateBehavior CRUD: Manage translations in *_i18n and *_translations tables with auto-translate and glossary support.

Benefits over normal PO editing

Prevent duplicates, missing translations, collisions.
Auto-Features like trim(), h(), newlines to <p>/<br>, escaping of %s.
Validate placeholders ({0}, %s, ...).
Preview and code excerpts of references.
Auto-Add Controller names (singular + plural).
Manage in Domains and export/enable/disable them.
Creates clean PO files with all translations in usage to easier diff changes.

Included translation services via APIs

Google (free, limited)
Yandex (free, limited)
Transltr (free)

Add your translation engine here in a heartbeat.

Installation

Including the plugin is pretty much as with every other CakePHP plugin:

composer require dereuromark/cakephp-translate

Then, to load the plugin run the following command:

bin/cake plugin load Translate -b -r
# If you haven't loaded the Tools plugin already
bin/cake plugin load Tools -b -r

Routes are needed for the backed, the bootstrap sets up a few defaults.

Run this in console to create the necessary DB tables:

bin/cake migrations migrate -p Translate

Recommendations

Use dereuromark/cakephp-queue for larger projects to avoid timeout issues when importing PO files.

Usage

Web Backend

Navigate to /admin/translate/ in your browser.

CLI

Run bin/cake translate.

TranslateBehavior Support

This plugin now includes comprehensive support for CakePHP's built-in TranslateBehavior and shadow table (_i18n) management - all in one unified interface.

Navigate to /admin/translate/translate-behavior for:

View All Shadow Tables: See all existing _i18n tables and their translation data
Detect Behavior Usage: Automatically detect which models are using CakePHP's TranslateBehavior
Find Candidates: Discover tables with translatable fields that don't yet have translation support
Generate Migrations: Create shadow table migrations with just a few clicks

Features:

Choose between Shadow Table (better performance, recommended) or EAV (more flexible) strategies
Select which fields to translate from your existing tables
Get complete, ready-to-use migration code with proper indexes and constraints
Step-by-step instructions for adding the behavior to your Table class
Automatic detection of translatable text fields
Preview of shadow table schemas and translation data
Shows which locales are in use
Identifies orphaned shadow tables (shadow tables without base tables)

Example workflow:

Navigate to /admin/translate/translate-behavior
Click "Generate Migration" on a candidate table (e.g., articles)
Select fields to translate (e.g., title, body)
Choose strategy (Shadow Table is default and recommended)
Copy generated migration code
Save to config/Migrations/AddI18nForArticles.php
Run bin/cake migrations migrate
Add behavior to your ArticlesTable class

Accessible from the main dashboard under "Quick Actions".

TranslateBehavior Entries CRUD

Manage individual translation entries in your TranslateBehavior tables directly from the web interface.

Navigate to /admin/translate/i18n-entries for:

Overview Dashboard: See all translation tables with entry counts and strategies
List & Filter: Browse entries by locale, field, or translation type
Edit Translations: Modify individual translation entries
Batch Auto-Translate: Translate multiple entries using configured translation engine
Glossary Suggestions: Get translation suggestions from your existing PO files

Supported Table Strategies:

EAV (*_i18n tables): Entity-Attribute-Value with foreign_key, field, content columns
ShadowTable (*_translations tables): Direct field columns like name, description

Auto Field Support: Tables with an auto boolean column can track machine vs. manual translations:

Machine translations (auto = true) can be safely re-translated
Manual edits (auto = false) are protected from automatic overwrites
Filter entries by translation type for quality review

See I18nEntries Documentation for detailed usage.

Web-based i18n Extract

Run CakePHP's i18n extract command directly from the web interface without needing CLI access.

Navigate to /admin/translate/translate-strings/run-extract for:

Dry Run Mode: Preview extracted strings before writing files
Custom Paths: Specify which directories to scan
Plugin Support: Automatic domain detection for plugin-type projects
Live Output: See extraction progress and results in real-time

Features:

Extracts to temp directory first, then copies to final location (ensures consistent behavior)
For plugins, automatically uses the plugin name as domain (e.g., translate.pot for Translate plugin)
Filters out unwanted POT files (like default.pot) for plugin projects
Shows string count and preview of generated POT files
Supports merge and overwrite options

Example workflow:

Navigate to /admin/translate/translate-strings/run-extract
Configure paths to scan (defaults to src/ and templates/)
Enable "Dry run" to preview first
Review the extracted strings
Disable "Dry run" and run again to write files
Import the generated POT file via the Extract/Import page

PO File Analyzer

Analyze PO/POT files for common issues and inconsistencies.

Navigate to /admin/translate/translate-strings/analyze to:

Upload or paste PO file content
Select from existing project PO/POT files
Detect formatting issues, missing translations, fuzzy entries
Identify placeholder mismatches between source and translation

Translation Coverage

The main dashboard shows translation coverage across all domains and locales:

Progress bars for each language
Counts of translated vs. total strings
Quick links to untranslated strings
Batch confirm functionality for reviewed translations

Tips

Use TinyAuth or Cake Authentication plugin to manage access to the translation backend for user groups.
Implement your own Translation engine if you want to have even better auto-suggest.

Configuration and documentation

Documentation

dereuromark / cakephp-translate

Maintainers

Package info

Statistics

Security