Lingua Forge

Version 2.7.1 — stable, in production, open for integration. This release is stable and already running production sites. It's no longer primarily about testing — the plugin has proven itself in real use — and the focus now is integration: other plugins/themes hooking into Lingua Forge's translation, routing, and SEO layers. Bug reports, compatibility reports, integration hooks requests, and pull requests are very welcome.

A note on WordPress.org. Multilingual support is a fundamental need for any publishing platform. Gutenberg's name honours Johannes Gutenberg not merely for inventing the printing press, but for making the dissemination of knowledge possible at scale — a mission that stops at a language boundary if the platform does not natively cross it. We believe first-class multilingual support belongs in WordPress Core and in Gutenberg itself, not perpetually deferred to a third-party plugin ecosystem.

Lingua Forge is not listed in the WordPress.org Plugin Directory — not because of code quality, security, trademark, or licensing concerns, but because WordPress.org maintains an undisclosed and ever-growing list of plugin names it considers reserved or off-limits, with no public registry, no appeal process, and no stated criteria. When gatekeeping operates without transparency, it does not protect a commons; it creates one.

Closing a door on a legitimate, well-intentioned contribution is itself a door that opens toward something less accountable. Let's not name what that less accountable future stands for. What is clear is that forces are at work within WordPress.org that do not want free multilingual support delivered for WordPress. That in itself is bad for the community, which is largely unaware of what is happening, and it compromises the platform's future — not only because of technological progress outside the ecosystem, but because of internal power structures that have contaminated the WordPress ecosystem itself.

It's closing up. It's losing its spirit. There is an opt-in bureaucracy at work, without effective oversight. Ancient Rome suffered from this; why should WordPress have a different destiny? Decline is often imperceptible to insiders whose beliefs have taken on a religious character. In projects like WordPress, "True Believers" (search for the term and you will find Eric Hoffer) make up the army. Feel free to star not the plugin — we want to see multilingual support in Core — but the reasoning behind it. If you want to do it for the plugin as well, you're welcome to. We have even offered our domain, https://lingua-forge.com, as a gift to the WordPress community, along with this plugin, in the hope of helping the platform do a better job for all of us.

Lingua Forge is distributed directly from this repository. It is permanently free, permanently open-source, and self-updates automatically after the first manual install. Collaboration welcome!

GitHub: https://github.com/leotiger/lingua-forge

Lingua Forge: https://lingua-forge.com

Lingua Forge is a WordPress plugin for sites that publish content in more than one language and want AI assistance built into the editorial workflow — without a paid third-party subscription service or a complex multi-plugin stack.

At its core it does three things that always end up intertwined on multilingual sites:

1. Routes visitors to the right language version of every page — via URL prefixes like /de/ or /fr/, or via language subdomains like de.example.com, with a language switcher block, browser language detection, and an admin panel that keeps translations linked and warns you when source content has changed.

2. Handles the full multilingual SEO surface natively — no companion plugin required — hreflang, a self-referencing canonical aligned with it, Open Graph with og:locale/og:locale:alternate, Schema.org JSON-LD with inLanguage (including a language-aware BreadcrumbList), a dedicated chunked XML sitemap with hreflang alternates, native IndexNow submission of every language version, per-language noindex, WooCommerce product schema, Social Icons block share: URL rewriting, and AI-powered SEO content analysis in both the Settings page and the block editor sidebar. A Compatibility tab shows live detection of any installed SEO plugin and explains exactly what Lingua Forge does for each feature area.

3. Gives editors an AI assistant directly inside the block editor — translate full pages, revise individual blocks, generate content from scratch, and fix quick-translate snippets on the fly, all without leaving WordPress. Results are previewed before anything is applied, and a terminology glossary ensures brand names and technical terms stay consistent across languages.

Everything ships as a single installable plugin. No external services beyond an AI provider API key (Anthropic, OpenAI, or Google Gemini — your choice), or WordPress's own built-in AI Client (WP 7.0+, no key stored by Lingua Forge). No subscription. No data leaves your server except the content you actively send for translation or generation.

---

Table of Contents

• How does it compare to WPML, Polylang, TranslatePress, Weglot, and MultilingualPress?
• Built on WordPress, not around it
• The story behind Lingua Forge
• Features
• Requirements
• Translations
• Recommended companions
• Built on Lingua Forge
• Installation
• Configuration
• Architecture
• Language Router — detailed reference
• AI Content Tools — detailed reference
• Known Issues and Troubleshooting
• Language Overrides
• Third-party compatibility
• Performance
• Author
• Changelog
• Screenshots
• Field notes
• License

---

How does it compare to WPML, Polylang, TranslatePress, Weglot, and MultilingualPress?

The short version: Lingua Forge covers the full multilingual workflow that the paid tiers of those plugins provide — language routing, complete multilingual SEO (hreflang, Open Graph, Schema.org, sitemap, IndexNow), FSE templates, translation groups, browser language redirect, translated slugs, and a built-in WooCommerce integration — and adds a deeper AI editorial layer than any of them ships natively, at zero licensing cost. The key difference is economic: no license fees, no annual renewals, no per-word translation credits. Use the AI features and you pay your provider directly at API rates; translate manually and the cost is zero.

The competitive landscape splits into three architectural camps. Post-based plugins (WPML, Polylang, MultilingualPress, Lingua Forge) create a distinct post record per language — the same approach Lingua Forge uses. String-replacement plugins (TranslatePress) intercept page output at render time and swap strings in place; no separate posts, but adds render overhead and can be brittle in complex block-template contexts. Cloud-proxy SaaS (Weglot) stores translations externally and serves them via CDN — fast setup, but your content lives in their infrastructure and pricing scales with word count.

Where Lingua Forge stands apart is the combination — every item below ships in the single free plugin, and no competitor offers the whole set:

• A complete native multilingual SEO layer — hreflang, a self-referencing canonical, Open Graph with og:locale, Schema.org JSON-LD with inLanguage (including a language-aware BreadcrumbList), a dedicated chunked XML sitemap with hreflang alternates, native IndexNow submission of every language version, per-language noindex, WooCommerce product schema and OG, Social Icons block share-URL rewriting, and AI-powered SEO content analysis — with no companion SEO plugin. The other post-based plugins delegate SEO to Yoast/Rank Math; none emit inLanguage, and none ship IndexNow natively.
• FSE-native from the ground up — language-specific template entities (page-de, header-ca) and a one-screen scaffold → AI-translate → fix-links → fix-nav-refs workflow, plus the Language Switcher block. Polylang Pro translates template-part content but not separate template entities; WPML's Site-Editor support is a retrofit with documented open issues; MultilingualPress gets FSE only by running each language as its own WordPress site.
• Every public Custom Post Type — included by default, excludable per type — the Lang column, AI metabox, FSE template routing, and link fixer apply to all public CPTs with zero setup; the System tab lists every post type and lets you exclude any one from routing in a single click (system types such as shop_order are excluded out of the box). This is the inverse of WPML and Polylang, where each CPT stays untranslated until you enable it per type — Lingua Forge works everywhere by default and steps aside only where you tell it to.
• Built-in WooCommerce at zero cost — shared-stock delegation (price, SKU, stock, images, variations with translatable descriptions, categories, attribute term names in block and classic themes, product brands) plus the commerce lifecycle: order-language capture, locale-switched transactional emails, cross-language coupons, consolidated sales and reviews, HPOS-compatible. WCML and Polylang-for-WooCommerce are paid add-ons; here it is part of the free plugin.
• WP-CLI for content translation and bulk automation — translate, retranslate, fill missing translations, and clear caches across a whole post type from a shell or cron job. Polylang's CLI is configuration-only; WPML's is import/export-only.
• An iterative AI editorial toolset inside the block editor — full-page and block-level translation, content generation with multi-turn refinement, meta-description and excerpt generation, quick-translate, behavior presets, glossary, and translation memory. No competitor ships this natively, and AI cost goes straight to your provider at published API rates — no credit intermediary.

Current gaps worth knowing: A general-purpose string translation UI (for third-party plugin strings outside the Language Overrides feature) is not yet included. For string translation today, Loco Translate is the recommended free companion — it provides in-admin .po/.mo editing, automatic sync with installed language packs, and developer extraction tools, and integrates cleanly alongside Lingua Forge with no conflicts. Slug translation is fully covered across all paths — full-page Translation dispatches the translated title via the Gutenberg Apply modal and WordPress derives the slug automatically; CLI commands set post_name from the translated title on every run.

→ Full competitive analysis — Lingua Forge vs WPML vs Polylang vs TranslatePress vs Weglot vs MultilingualPress

Built on WordPress, not around it

Lingua Forge is designed to stay as close to WordPress core and Full Site Editing conventions as possible. Translations are native WordPress posts. FSE templates, template parts, and navigation menus are native wp_template, wp_template_part, and wp_navigation posts — not string-swapped versions of a single shared entity. Blocks are blocks. Routing uses standard WP_Query. Nothing sits outside WordPress's own data model.

This is intentional and measurable: no runtime dependencies ship with the plugin (all dev tooling lives in dev/), Block API v3 is used throughout, the frontend carries no jQuery dependency, REST routes register at rest_api_init, and standard WordPress i18n and security conventions are applied without exception. The result is a plugin that behaves predictably alongside the rest of the WordPress ecosystem — no parallel data layer, no recomposition step, no render-time interception.

The story behind Lingua Forge

If you want to understand where this plugin came from and why it exists as a free, open-source project rather than another subscription product, the blog post below covers the full picture in plain language — the necessity that started it, the weeks of intense work, the real website (cal-talaia.cat) that served as the test environment, the honest account of building an AI plugin with AI assistance (including the tokens spent and the many corrections along the way), and the social argument for why multilingual tools should belong to everyone.

→ From a handful of messy files to a plugin anyone can use

Features

Language Router

• Two URL structure modes — path prefix (example.com/de/) or subdomain (de.example.com), selectable from Settings → Router → URL structure. Subdomain mode requires wildcard DNS and TLS; path prefix mode works with standard WordPress permalink settings.
• Language detection from URL prefix (/de/), subdomain host (de.example.com), query param (?lang=de), and cookie
• Custom rewrite rules for language-prefixed URLs and category archives (path mode); no extra rules needed in subdomain mode
• Post and page translation groups linked via a shared TRID (UUID)
• Outdated translation tracking — warnings when source content is updated after a translation was synced
• Sync and Template Sync — a "Sync" button in the post list Lang column, shown on every language version of a translated post (including the primary), retranslates FROM that post's language INTO every other configured language in one click: missing languages are created, existing ones force-refreshed in place. "Template Sync" does the same for FSE template assignment only, with no AI call. Syncing FROM a secondary-language post can back-translate onto the primary — guarded by two independent off-by-default safeguards (Settings → Behavior → Sync and → WooCommerce) plus a confirmation dialog. Public API: linguaforge_sync_translations() / linguaforge_sync_templates()
• Full FSE template localisation — language-specific templates (page-de, single-fr, search-en) are auto-assigned when a post's language is set. From Settings → Router you can scaffold a language copy of any template or template part in one click, AI-translate it, fix all internal links to point at the correct language equivalents, fix template-part slug references (footer → footer-ca), and fix wp:navigation ref IDs so each header and footer loads the correct language menu — all without CLI or manual database work. "Re-create" / "Re-create all" buttons force-overwrite an existing template with a fresh copy from the active theme (discarding Site Editor customisations), theme-scoped so same-slug templates belonging to different themes are never confused. A "Recreate All Languages" orchestrator on Settings → Router → Language Setup chains re-create → translate → fix-links → fix-parts across every active language in one run.
• Language-specific template parts — scaffold, AI-translate, fix links, and fix navigation references for header-{lang}, footer-{lang}, and any other template part. Each is a native wp_template_part post with its own content, independent of the base language version. Same Re-create / Re-create all tooling as templates, plus its own "Recreate All Languages (Template Parts Only)" orchestrator.
• Language navigation menus — create per-language wp_navigation copies with AI-translated link labels and language-prefixed internal URLs. The Fix Nav action rewrites wp:navigation ref IDs inside template parts to point at the correct copy.
• Site Editor page-list language filter — when the Site Editor is opened on a navigation or template post, the sidebar page-list picker automatically scopes its /wp/v2/pages REST requests to the current navigation's language. The filter is resolved synchronously at PHP render time (no race condition on the initial load) and corrects itself asynchronously when the navigation ID is not in the initial URL.
• hreflang tags for singular, archive, and paginated views; automatically suppresses duplicate hreflang output from Yoast SEO, Rank Math, AIOSEO, and SEOPress via filter — see Settings → SEO → Hreflang
• Language switcher — available as a Gutenberg block (LSFLR Switcher), a [lsflr_switcher] shortcode, and a classic Lsflr_Switcher_Widget (Appearance → Widgets). All three produce identical output and support the same direction, show, and customLabel options. The linguaforge_switcher_output filter wraps all three entry points so themes and third-party plugins can customise the HTML without touching templates
• Admin link fixer — scans translated pages for internal links pointing to the wrong language version and repairs them via AJAX
• Plugin translation override — custom .mo files placed in wp-content/uploads/lingua-forge/i18n-overrides/ are loaded automatically, overriding third-party plugin strings for each locale (e.g. swapping "room" → "apartment" in VikBooking). Files survive plugin updates. Manage them from Settings → Lingua Forge → Language Overrides or drop them in directly via FTP/SFTP.
• Full Custom Post Type support — every public CPT (WooCommerce product, any third-party CPT) automatically receives the full admin layer: Lang column with outdated/missing indicators and Retranslate/Translate-missing buttons, language and status filter dropdowns, quick-edit language control, AI translation metabox, FSE template selector, Translation Memory eligibility, and link-fixer scan. No configuration required. Three opt-out filters available: linguaforge_column_post_types, linguaforge_ai_metabox_post_types, linguaforge_link_fixer_post_types
• WooCommerce integration — translated products carry only content fields (title, description, meta description); price, SKU, stock, dimensions, images, and taxonomy assignments are served transparently from the source-language product at runtime. Variable products are fully supported: translated product variations are created automatically with their descriptions (_variation_description) translatable via the standard Retranslate button, while operational meta (price, stock) delegates from source variations. Attribute term names display in the visitor's language (e.g. "Rot"/"Blau" on DE pages) via _lf_term_name_{lang} termmeta in both classic templates and WC block themes. Product brand (product_brand, native WC 10.x) is delegated automatically; third-party brand taxonomies are registerable via the linguaforge_wc_delegate_taxonomies filter. REST API writes to translated products return HTTP 422 with the source product ID for safe resolution. Requires WooCommerce 9.0+ and WordPress 6.9+
• DB index on wp_postmeta (meta_key, meta_value) created on activation for fast _lang queries

SEO

Lingua Forge provides a complete multilingual SEO layer. No additional SEO plugin is required. Configure everything from Settings → SEO.

Hreflang — <link rel="alternate" hreflang> for every configured language on every page, including x-default. Automatically suppresses duplicate hreflang output from Yoast SEO, Rank Math, AIOSEO, and SEOPress via WordPress filter hooks.

Open Graph + Twitter Cards — outputs og:locale (current language) and og:locale:alternate (every other configured language) on every page — the multilingual OG signals that SEO plugins cannot produce without knowledge of your routing configuration. In auto mode it also outputs the full OG base set (og:type, og:title, og:description, og:url, og:image, Twitter Cards) when no SEO plugin is detected, deferring to the SEO plugin when one is present to avoid duplicate tags. Default OG image with full fallback chain: featured image → site logo → site icon → admin-configured default.

Schema.org JSON-LD — outputs Article/WebPage on singular posts and pages, WebSite on the front page/blog index, and Product on WooCommerce product pages (when WC is active). Every type includes the inLanguage BCP 47 annotation. Defers entirely when Yoast/Rank Math is detected — conflicting JSON-LD graphs cause validation errors and there is no clean way to supplement an existing graph.

XML Sitemap — dedicated multilingual sitemap at /lf-sitemap.xml with xmlns:xhtml namespace and <xhtml:link rel="alternate" hreflang> entries for every translation group. Announced automatically in robots.txt. One-click Bing and Yandex ping buttons. robots.txt detection panel with option to add the Sitemap: directive to an existing physical file.

Social Share — extends the WordPress Core Social Icons block. Set any icon's link URL to share:facebook, share:x, share:linkedin, share:whatsapp, share:telegram, share:email, share:reddit, share:pinterest, share:mastodon, share:copy, share:native, or share:auto; Lingua Forge rewrites it at render time. The JS actions (share:copy, share:native, share:auto) use the Clipboard API and Web Share API with clipboard fallback, and show a toast notification on success.

SEO Content Analysis — rule-based 0–100 score covering title length, meta description quality (uses AI-generated meta description when available), word count, heading structure, image alt coverage, and internal link profile. Three entry points: (1) Single-post — click Analyze on any item in Settings → SEO → Analysis to get an instant score for that post. (2) Block editor sidebar — the Document panel shows the current post's score and a "Run AI Analysis" button that opens a modal with natural-language recommendations, title suggestions, and meta description improvements. (3) Batch / Multilingual parity — a card grid in Settings → SEO → Analysis (one card per active language) lets you analyze an entire language in one pass and view the results as a Multilingual SEO overview: per-language tabs showing every post with its score, a direct edit link, the source-language title for cross-language parity comparison, post type, and profile. WooCommerce system pages are automatically excluded from batch scoring. A hint below the heading explains that low scores often reflect structural limits rather than improvable content.

WooCommerce product SEO (requires WooCommerce) — adds og:type=product, og:price:amount, og:price:currency, og:availability, and their product: namespace equivalents on product pages. Product schema includes translated name, description, inLanguage, and a correctly resolved offers object (price and availability from the source-language product via MetaDelegate).

Compatibility — the Compatibility tab shows live detection of any active SEO plugin (Yoast, Rank Math, AIOSEO, SEOPress) with a per-feature explanation of what Lingua Forge is doing and why — no manual configuration needed.

Meta description field — custom field editable in the Classic meta box and Block Editor on every public post type. Character counter with green/amber/red guidance (140–160 optimal range). Fallback chain: AI-generated field → post excerpt → trimmed content. AI generation available in one click from the AI metabox (_linguaforge_meta_description postmeta key, readable by third-party integrations).

AI Content Tools

Supports Anthropic Claude, OpenAI, Google Gemini, and WordPress's own built-in AI Client (WP 7.0+, routed through Settings → Connectors — Lingua Forge stores no key for this provider) as interchangeable backends. All results appear in a review panel — nothing is applied automatically.

• Meta Description Generator — language-aware, 140–160 character output with SEO quality indicator
• Excerpt Generator — concise editorial excerpt up to 240 characters, language-aware
• Content Translation — full post and page translation preserving all Gutenberg block markup, block attribute strings (accordion summaries, image alt text, etc.), and footnotes. Chunk mode for translating individual snippets
• Content Generator — drafts or rewrites post content from hints, tone, and output-type controls. Outputs native Gutenberg block markup
• Quick Translate — admin toolbar popover with three modes: Translate any text snippet into a chosen language, Create new content from hints and tone, and Refine any result iteratively with additional instructions. Also available inside the Gutenberg / FSE editor toolbar
• AI Behavior Presets — four named presets (Standard, Technical / Scientific, Legal / Compliance, Creative / Marketing), each with a tuned temperature and system-prompt addendum. Configurable globally from Settings → Behavior and overridable per post from the Lingua Forge metabox (Translation and Content Generator only)
• Translation Memory — opt-in block-level translation cache shared across posts; only untranslated blocks are sent to the API, reducing token usage for recurring content. Enable from Settings → AI Usage & Cache → Translation Memory
• Glossary — user-managed terminology table per language pair. Terms are injected into every translation prompt. Manage from Settings → Glossary
• Side-by-side diff preview — "Apply to Editor" opens a two-column modal showing current vs translated content before anything is written
• Footnote tab in the Block Action popover — translate or revise individual footnotes without switching to chunk mode; only visible when the popover is opened from inside the WordPress footnote editing UI (not from the main block toolbar)
• AI Usage tracking — every API call is logged by feature, provider, model, and date. A usage summary (requests, input tokens, output tokens) is available in Settings → AI Usage for any date range
• SHA-256 hash-based result caching in a dedicated custom table; per-language translation cache; force-refresh control
• Configurable model endpoints per provider and tier from the Settings page — no code changes needed when a new model version ships
• WP-CLI support — six commands for scripted and automated workflows: translate, retranslate, fill_translations, missing_translations, fix_nav_lang, and cache_clear. All translation commands accept --with-meta-description to generate and save an AI meta description for each target post in the same pass
• Automatic Translation Backfill — opt-in hourly scan (off by default) that finds posts missing one or more configured-language translations and queues them for creation via the same async pipeline as linguaforge_queue_translation(). Enable from Settings → Behavior → Automatic Translation Backfill; scope post types with the linguaforge_backfill_post_types filter (WooCommerce products/variations excluded by default)
• Comment Translation (2.7.0) — off by default. Mirrors an approved comment onto every language version of its post as a real, translated comment. Manual mode (default) translates via a "Translate"/"Translate missing" action on the Comments screen; opt-in Automatic mode translates the moment a comment is approved. Nested-reply backfill is depth-capped (default: 2 levels below the original comment) to bound AI spend on deep threads. New Comments-screen "Lang" column and language filter dropdown. WooCommerce product reviews are unaffected — they keep their existing shared-review-pool model (ProductReviewRouter)

---

Requirements

• WordPress 6.4 or later (block theme / FSE recommended)
• PHP 8.1 or later
• Permalink structure set to anything other than Plain
• An API key for at least one supported AI provider (Anthropic, OpenAI, or Gemini) — or WordPress's built-in AI Client (WP 7.0+) configured via Settings → Connectors, no key stored by Lingua Forge

Optional — WooCommerce integration: WooCommerce 9.0 or later is required (which in turn requires WordPress 6.9 or later). The core plugin — language routing, full SEO layer, AI tools — works on WordPress 6.4 without WooCommerce. If WooCommerce is not active the WooCommerce delegation layer and WooCommerce-specific SEO output are silently skipped.

Multisite: Lingua Forge is not tested on WordPress Multisite. Per-site activation — each site in the network manages its own languages, settings, and AI credentials independently — is expected to work. Network-wide activation is not supported and may produce unexpected behaviour.

---

Translations

Lingua Forge's own interface is translated into 26 languages, so you can work in your native language right out of the box:

Code	Language	Code	Language
ar	Arabic	ko_KR	Korean
ca	Catalan	nl_NL	Dutch
de_DE	German	pl_PL	Polish
el	Greek	pt_PT	Portuguese
en_US	English (US)	ru_RU	Russian
es_ES	Spanish	sv_SE	Swedish
eu	Basque	sw	Swahili
fa_IR	Persian	th	Thai
fr_FR	French	tr_TR	Turkish
hi_IN	Hindi	ur	Urdu
hu_HU	Hungarian	zh_CN	Chinese (Simplified)
id_ID	Indonesian	it_IT	Italian
ja	Japanese	km	Khmer

All translation files (languages/lingua-forge-{locale}.po/.mo/.l10n.php) are bundled in the plugin. To contribute a new translation or improve an existing one, open a pull request against the languages/ directory. Translation are AI generated, you may encounter inconsistencies, e.g. Light (AI tier) translated as Llum to Catalan, which should obviously be Lleuger... AI isn't perfect at all and Loco Translate does not offer a prompt to establish context awareness, what makes a feature implementation that subsitutes Loca Translate a roadmap feature for Lingua Forge... depende on your usage and demand...

---

Recommended companions

Loco Translate — for translating third-party plugin and theme strings (.po/.mo editing, automatic language-pack sync, developer extraction). Integrates cleanly alongside Lingua Forge with no conflicts.

---

Built on Lingua Forge

Lingua Forge is also a foundation other plugins build on, not just a standalone tool.

Agnosis — a free, federated WordPress plugin for independent artist collectives: artists submit work by email, AI writes the description and corrects weak photos, and published work federates to Mastodon and Pixelfed via ActivityPub. Agnosis declares Lingua Forge as a required companion plugin (Requires Plugins header — WordPress refuses to activate Agnosis without it) and relies on it for every multilingual surface: the required language field at artist admission, per-recipient locale-switched emails, and native-language fidelity for artwork titles and slugs. A companion FSE block theme, agnosis-theme, ships alongside it. Live at agnosis.art.

If you're building a plugin that needs multilingual routing rather than reinventing it, Lingua Forge's public API — linguaforge_trigger_translation(), the REST endpoints, and the hooks documented in CONTRIBUTING.md — is designed to be built on the same way.

---

Installation

The first install is manual (Lingua Forge is self-distributed — see the note at the top of this file):

1. Download the latest lingua-forge-{version}.zip from the Releases page
2. In your WordPress admin go to Plugins → Add New → Upload Plugin, choose the ZIP, and click Install Now
3. Activate Lingua Forge from Plugins → Installed Plugins
4. Go to Lingua Forge in the admin sidebar, select a provider, and enter your API key

After the first install, updates are automatic. WordPress checks for new releases every 12 hours and displays the standard update badge in Plugins → Installed Plugins when one is available — one-click update from there, no manual download required.

wp-content/
  plugins/
    lingua-forge/
      lingua-forge.php       ← main plugin file
      language-router/       ← Language Router + full SEO layer (hreflang, OG, schema, sitemap, social share)
        includes/seo/        ←   SeoManager · SchemaManager · SocialShare · SitemapManager
      meta-description/      ← Meta description meta box module (legacy; SEO suite is in language-router/includes/seo/)
      ai/                    ← AI content tools + Settings page with SEO tab + WooCommerce SEO

If you are migrating from the mu-plugin versions of these tools, deactivate or remove wp-content/mu-plugins/language-router/, wp-content/mu-plugins/meta-description/, and wp-content/mu-plugins/wpenhance-ai/ (or wpai/) before activating Lingua Forge to avoid duplicate hooks.

---

Configuration

Language Router

The source language and active language list are configured from Settings → Lingua Forge → Router — no code changes required. The filters below are developer overrides that take precedence over the stored settings:

// Override the source language programmatically (takes priority over the Router setting)
add_filter( 'lf_primary_language', fn() => 'ca' );

// Override the active language list programmatically
add_filter( 'lf_languages_list', fn() => ['ca', 'es', 'en', 'de', 'fr'] );

Filters reference

The handful of Language Router filters most relevant here: lf_primary_language, lf_languages_list, lf_lang_force_locale, lf_lang_fallback_map, lf_lang_default_fallback, lf_base_domain, lf_hreflang_mode, lf_hreflang_x_default, lf_i18n_overrides_dir, and linguaforge_translation_languages (AI target-language list). Full signatures, defaults, and every other hook in the plugin: HOOKS.md.

WordPress language setup

Languages are configured entirely inside Settings → Lingua Forge → Router. There is no need to install WordPress language packs or visit Settings → General → Site Language to add a language to your site — Lingua Forge manages its own language registry independently. Adding or removing a language automatically flushes the rewrite rules so the new URL prefix is live immediately, with no manual Permalinks save required.

WP site language vs. primary content language

WordPress site language (Settings → General → Site Language) controls the admin interface and the locale WordPress uses internally.

Primary content language (set in Settings → Lingua Forge → Router) is the language your actual content is written in — the language that maps to the root URL path (no prefix) and acts as the source for all translations. Developers can override it via the lf_primary_language filter.

Requirement: the WP site language must be one of the languages used for content.

Lingua Forge builds its valid-language list from installed WordPress language packs, plugin .mo files in the i18n-overrides folder, and the explicitly configured primary language. WordPress's own site locale is intentionally excluded from this list when the primary content language is explicitly set — to prevent the admin UI language from being treated as a content language.

However, WordPress core and WooCommerce use get_locale() directly in a number of operations (object-cache keys, REST API locale, early text domain loads, locale-sensitive number and date formatting). Even with Lingua Forge switching the locale via switch_to_locale(), some of those operations happen before or outside the switch. When the WP site language is completely outside the content language set, mismatches accumulate:

• WooCommerce product queries break — language detection falls back to the WP site locale, injecting the wrong _lf_lang constraint and returning zero products.
• Product image delegation fails — source product ID resolution relies on correctly identified language codes throughout the TRID chain.
• The language switcher may render a spurious non-content language option (fixed in 2.2.16 for the routing layer, but the locale-level conflicts in WooCommerce remain).
• REST API responses always use the WP site locale (REST is excluded from locale switching); this affects Gutenberg block data fetched via REST.

Supported configurations:

WP site language	Content languages	Result
ca	ca (primary), es	Fully supported — site locale matches primary content
es_ES	ca (primary), es	Fully supported — site locale is one of the content languages
en_US	ca (primary), es, en	Fully supported — English is an active content language
en_US	ca (primary), es	⚠ Not supported — English is not a content language; WooCommerce and product image delegation will not work reliably

Recommendation: Set Settings → General → Site Language to the primary content language, or to one of the active secondary languages. For WooCommerce sites the restriction is strict — mismatched locales cause product queries and image delegation to fail in ways that cannot be reliably patched at the plugin layer.

---

AI Content Tools

Choosing a provider

Navigate to Settings → Lingua Forge and select the active provider from the dropdown, or define the constant in wp-config.php:

define('LINGUAFORGE_PROVIDER', 'anthropic'); // 'anthropic' | 'openai' | 'gemini' | 'wp-ai-client'

wp-ai-client (WordPress 7.0+) delegates to WordPress core's own wp_ai_client_prompt() builder instead of a direct HTTP call — Lingua Forge stores no API key for it; credentials are managed by the site admin through Settings → Connectors. Falls back gracefully (with a logged error) on WordPress versions older than 7.0.

API keys

Enter keys directly from Settings → Lingua Forge. Keys are stored encrypted in wp_options using AES-256-GCM (with the provider slug as authenticated data) derived from WordPress's own auth salts — plaintext keys never touch the database.

For sites where development, staging, and production share a wp-config.php copy (and therefore the same wp_salt('auth') value), define a unique LINGUAFORGE_SECRET constant in each environment to ensure each has an independent encryption key:

define( 'LINGUAFORGE_SECRET', 'your-64-char-random-string-here' );

Generate a value with openssl rand -base64 48. Note: changing this constant invalidates stored ciphertexts, so re-enter your API keys afterward.

Fallback resolution order (highest to lowest priority):

1. Encrypted value in wp_options (set via the Settings page)
2. Server environment variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY)
3. PHP constant of the same name defined in wp-config.php

Models

Navigate to Settings → Lingua Forge → Models to override the model string for any provider and tier:

Tier	Anthropic	OpenAI	Gemini	Used by
Light	claude-haiku-4-5-20251001	gpt-4o-mini	gemini-2.5-flash-lite	Meta Description, Excerpt Generator
Quality	claude-sonnet-4-6	gpt-4o	gemini-2.5-flash	Translation, Content Generator

These are the built-in defaults for each provider. Leave a field blank to use the built-in default for your active provider. To update to a new model version when one ships, enter the new identifier in Settings — no code change or deployment needed.

The wp-ai-client provider has no model-string configuration here — model routing is delegated entirely to WordPress core's Connectors settings.

Token budgets and input limits for