# translate-sidecar: post translations kept in their own table

[translate-sidecar](https://github.com/IndianOpinion/translate-sidecar) is a WordPress plugin for operators of multilingual sites. It keeps each translation in a table of its own, serves it at /xx/slug/ as a view of the original post, and guards machine translation against partial and wrong-script output. It is MIT licensed, and v0.1.0 was released on 19 November 2026.

It was written from scratch from an idea, as part of a set of utilities built between 11 and 19 November 2026 by language-model coding agents under the editor's direction. It has not run on a live site. Indian Opinion itself has been English only since September 2026 and does not publish other languages. This plugin is released for other sites.

## The problem

The common way to translate a WordPress post is to create a second post per language and link the copies. That has four costs.

- Every language multiplies the posts, post meta, attachment links and revisions tables. Every plugin that loops over posts now loops over copies.

- The copies drift. A correction or a new featured image on the original does not reach them, and structured data describes separate articles instead of one translated work.

- Machine translation fails quietly. A model stops halfway, answers in the source language or a neighbouring script, or drops a paragraph, and the page goes out under the wrong language code.

- Announcing a large set of thin machine-translated pages to search engines at once risks a site-wide demotion.

## What it does

- Stores one live row and at most one candidate row per post and language. It never creates a post per language.

- Routes /xx/slug/ to the original post's template with the title, body, excerpt, document title, lang and dir swapped. Images, author, dates and comments stay the original's.

- Prints a self-referencing canonical, an hreflang cluster identical on every member, og:locale and JSON-LD with inLanguage.

- Builds one sitemap per indexable language.

- Translates through an adapter: manual for human translators, a language model through llm-json-php, or your own caller.

- Offers side-by-side review with a guard report, rollback to three prior versions, withdrawal, a Site Health check, a REST API and WP-CLI.

## How it works

Translations live in one table keyed on post and language, with states queued, running, failed, candidate, live, rejected, withdrawn and prior. A unique key on a generated column enforces one live and one candidate row where the database supports it, and a lock in code covers the rest. A translation memory table and a counters table complete the schema. Nothing joins post meta.

The segmenter cuts the body at block level. Inline tags become numbered placeholders such as {1}text{/1}. URLs, attributes, block comments, code, shortcodes and embeds never reach the model, and the markup between segments is kept byte for byte.

The guards run on every call and on the assembled result. Every segment must come back once, untruncated, with its placeholders. The result must keep its structure, stay inside a length ratio of 0.4 to 3.0, keep its numbers, not come back unchanged, match the declared and detected language, and be mostly in the target script. Any failure fails the whole job and stores nothing. The script guard proves the script, not the language, so a detector can be plugged in with translate_sidecar_detect_language.

wp translate-sidecar request 123 --lang=fr
wp translate-sidecar run
wp translate-sidecar guard <row-id>
wp translate-sidecar approve <row-id>

## Guard rails

- Every language starts with publish, index and auto all off. A candidate stays a candidate until a reviewer approves it.

- With publish on and index off, pages carry noindex, follow. The README advises turning indexing on for one language at a time.

- A daily call cap of 100, an optional character cap, a kill switch by setting, constant or network option, and a spend-meter hook.

- Posts over 200 segments are refused, so one post cannot eat the cap. Posts under 150 source words are refused.

- Routing fails closed for anything unpublished, held or protected.

- Only post text goes to the provider: no author names, emails or comments. Model output passes through wp_kses_post. The prompt presents segments as data, which lowers the risk of hidden instructions, and review remains the control.

- API keys are read from constants or environment variables, never stored in an option.

## What review changed

- llm-json-php was not a real dependency. It now is, through a typed adapter that maps the library's failures onto the runner's terms: credit pause, truncated, bad shape, immediate failure or backoff.

- A job left running by a dead process stayed there for ever and blocked new requests for that post and language. Ticks now requeue it after an hour, or fail it as stalled.

- A language prefix could collide with a post or category served at that path by the permalink structure. It is now refused, and Site Health runs the same checks.

- The batched link lookup replaced a linked post's live rows with one language, hiding its other languages from a later hreflang cluster in the same request.

- Sitemap pages did one query per URL when alternates were on. Clusters now load in one query per page.

## Limits and what is next

- Only post text is translated: title, body, excerpt, alt text and any SEO fields you feed in. Menus, widgets, terms, archives and theme strings stay in the site language.

- Translations use the original slug under the prefix. No translated slugs.

- The language home /xx/ redirects to the site home.

- Text inside shortcodes other than classic captions is not translated.

- Running another multilingual plugin at the same time is unsupported.

- Must-use installation is not supported, because there are no activation or uninstall hooks.

There are no open issues. This is v0.1.0, tested on stubs, mocks and a throwaway MySQL. The suite has 159 tests and 1130 assertions, including six integration tests against a throwaway MySQL 8.0, and the model adapter was tested against the library's mock transport with no network. Static analysis and code style checks pass. No real model, search engine or page cache has been involved, and CI has not yet run on GitHub.

## Install

Requires PHP 8.1 or later, WordPress 6.4 or later, MySQL 5.7 or later or MariaDB 10.4 or later, and pretty permalinks. The model adapter depends on llm-json-php, which is not on Packagist yet, so add its repository first.

composer config repositories.llm-json-php '{"type": "vcs", "url": "https://github.com/IndianOpinion/llm-json-php", "no-api": true}'
composer require indianopinion/translate-sidecar

Without Composer, unzip a release into wp-content/plugins/translate-sidecar/. The manual adapter and a site-supplied caller work without the library.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [translate-sidecar on GitHub](https://github.com/IndianOpinion/translate-sidecar)

Canonical: https://indianopinion.org/blog/open-source/translate-sidecar/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
