Skip to content
Baseworks KB

WPML Translation Automation Plan

Created 2026-03-29
Tags infrastructurewpmltranslationplan

Status: Planning — investigation needed before implementation Date: 2026-03-29 Context: Currently translating content manually via WPML’s Advanced Translation Editor. This plan documents three approaches to streamline the workflow, from current manual process to fully automated.

Current Workflow (Option 3 — in use now)

Section titled “Current Workflow (Option 3 — in use now)”
  1. Claude Code translates the article content into Japanese
  2. Translation is saved in the same vault note as the English version (below the article body)
  3. All hyperlinks updated to /ja/ versions where Japanese pages exist
  4. WordPress metadata (excerpt, SEOPress, photo captions/alt text) translated separately
  5. Patrick creates the Japanese post shell in WPML’s translation editor
  6. Patrick pastes each translated section into the corresponding WPML field
  7. WPML handles the language relationship linking automatically

Pros: Safe, WPML manages relationships correctly, no risk of breaking anything Cons: Manual paste step for every article, tedious for long content

Option 2 — WP-CLI Post Creation + Database Linking

Section titled “Option 2 — WP-CLI Post Creation + Database Linking”
  1. Claude Code creates the translated post via wp post create with full Gutenberg block content
  2. Manually insert the WPML translation relationship in wp_icl_translations table
  3. Set trid (translation ID) to match the English post, language_code to ja

Investigation needed:

  • Query: SELECT trid, language_code, element_id FROM wp_icl_translations WHERE element_id = {english_post_id}
  • Insert: match the trid, set language_code = 'ja', element_id = {new_japanese_post_id}
  • Risk: WPML may have additional metadata or hooks that need to fire when creating translations. Database-only linking might leave the post in an inconsistent state.
  • Test on staging first (pracstage.baseworks.com)

Pros: Fully automated content creation, only DB linking is manual Cons: Fragile — WPML schema could change between versions, not officially supported

Option 1 — WPML REST API (Preferred Long-Term)

Section titled “Option 1 — WPML REST API (Preferred Long-Term)”
  1. Check if WPML REST API is enabled: wp option get wpml_rest_api_enabled or check WPML settings
  2. If available, use endpoints like:
    • POST /wp-json/wpml/v1/translations to create translation relationships
    • Or WPML’s Translation Management API
  3. Claude Code sends the full translated content + metadata via API, WPML handles linking

Investigation needed:

  • WPML version on baseworks.com (check wp plugin list | grep sitepress)
  • Whether WPML REST API endpoints are available (varies by WPML plan — may require WPML CMS or higher)
  • API documentation: check WPML’s developer docs for available endpoints
  • Authentication: would use the same WP REST API auth as other API calls

Pros: Clean, officially supported, fully automatable Cons: May require WPML CMS license tier, API may not cover all fields (SEOPress, ACF)

Rules for All Approaches

Section titled “Rules for All Approaches”
  • Japanese slugs always use the English slug: /ja/{english-slug}/
  • All baseworks.com internal links in Japanese content must point to /ja/ versions where available
  • Photo captions, alt text, SEOPress fields, and excerpts must all be translated
  • Product names (Baseworks Primer, Smart Revisit, PrimerPrint, Practice Platform) stay in English
  • Form names (Star Form, Squat, etc.) stay in English
  • The “BRAIN FODDER” heading stays in English (brand element)
  • Photographer credit stays in English (Andrew Miller / awesomephotography.ca)

Next Steps

Section titled “Next Steps”
  1. SSH to baseworks.com and check WPML version + REST API availability
  2. If REST API is available, test with a simple page translation on staging
  3. If not, test Option 2 (WP-CLI + DB linking) on staging with a test post
  4. Document whichever approach works as a repeatable workflow or skill

Relationship to Existing Plans

Section titled “Relationship to Existing Plans”

The wpml-translation-workflow document is the comprehensive implementation plan — it includes the mu-plugin code (bw-wpml-translation-api.php), vault JSON file structure for translations, REST API endpoints, Elementor/WooCommerce handling, language rollout phases, and session flow examples. That document supersedes Options 1 and 2 in this plan by providing a complete custom REST API solution.

This automation plan documents the interim approach (Option 3 — manual paste) that is in use until the mu-plugin is deployed, along with the translation rules that apply regardless of which approach is used.

Section titled “Related”
  • wpml-translation-workflow — full implementation plan with mu-plugin code, REST endpoints, and vault file structure (the primary reference)
  • wpml-migration-plan — future architecture where WPML is replaced by Cloudflare Worker (vault translation files are portable to this)