Langconv Laravel Package

Technical Evaluation

What it is. LangConv is the conversion engine extracted from MediaWiki's LanguageConverter — the component behind zh-hans/zh-hant/zh-cn/zh-tw/zh-hk/zh-sg variant rendering on Wikipedia. It converts one source text into multiple script variants (Chinese Simplified/Traditional, Serbian Cyrillic/Latin, and a few others) using compiled FSTs and replacement rules. It is an engine, not a dictionary.

Architecture fit

• Pure PHP, no framework coupling, Composer-installable. There is no Laravel service provider, config, facade, migration, or queue integration — and that is fine. It slots in as an infrastructure adapter behind an interface you own, e.g. ScriptConverter::convert(string $text, string $variant): string.
• Works equally well for read-time conversion (render on request) and write-time fan-out (materialize variants at save).
• You inherit MediaWiki's variant model: variant codes, fallback chains (zh-hk → zh-hant → zh), and the -{...}- exception markup. That is real semantic coupling, not just an API surface.

Integration feasibility

• Composer install is trivial; verify the PHP constraint against your runtime (Laravel 10/11 on PHP 8.1–8.3 generally fine).
• The critical gotcha: engine vs. data. The package provides the conversion machinery; the actual Chinese conversion tables (ZhConversion) live in MediaWiki core and must be sourced and compiled/baked separately. Without that pipeline you have a high-quality engine with an empty dictionary. Budget for a build step, an artifact, and a refresh cadence.
• A 2–4 day spike is enough to decide: install, load a table set, convert a 500–1,000 string sample of your real content, compare against OpenCC and ICU Transliterator.

Technical risk

• License: GPL-2.0. This is the gating item. Hosted/backend use is typically acceptable; distributing a derivative work (on-prem appliance, shipped package, desktop bundle) triggers copyleft obligations that may be incompatible with a proprietary product. Legal review is a gate, not a checkbox.
• Upstream workflow. The GitHub repo is an explicit mirror; development and issue tracking happen on Gerrit/Phabricator. Do not expect GitHub PRs or issues to be actioned. Releases follow MediaWiki's cadence, not a community semver rhythm.
• Ecosystem signal is weak but misleading. 2 stars, 0 recorded dependents, score 0.01 — this measures packaging popularity, not correctness. The engine runs at Wikipedia scale.
• Quality is bounded by data, not code. Conversion is inherently one-to-many; without phrase-level rules you get character-level artifacts in names, proper nouns, and idioms. Your test corpus matters more than the library version.
• Version drift. Tables generated for one MediaWiki release may not match the format an older/newer engine expects. Pin both together.

Key questions

1. Do we distribute the application, or is it hosted-only? (License gate — answer this first.)
2. Where do the variant tables come from, who refreshes them, and how do we validate a refresh?
3. Is read-time conversion acceptable, or do we need precomputed variants for search and SEO?
4. What is the measurable quality bar (human-reviewed sample, character error rate, golden corpus)?
5. Chinese only, or also Serbian/Kazakh/Uzbek?
6. What is the fallback? OpenCC (Apache-2.0, mature, PHP bindings) or ICU Transliterator (bundled with ext-intl) — if the adapter interface exists, swapping is a one-class change.

Integration Approach

Stack fit

• No native extensions, no daemons, no external services — deployable on standard PHP-FPM, and a particularly good fit for Octane/Swoole where table loading is amortized across requests instead of paid per request.
• Usable from Blade, API Resources, queue jobs, and Artisan commands with the same adapter.

Migration path

• Never rewrite stored content. Keep one canonical source; derive variants on read first, then optionally materialize on write for search indexing.
• Introduce behind an interface, bind in a service provider, and gate variant routing behind a feature flag so it can be disabled per-locale.

Compatibility

• Map your internal locale registry to MediaWiki variant codes explicitly (zh-hans, zh-hant, zh-cn, zh-tw, zh-hk, zh-sg, zh-my, zh fallback). Do not pass arbitrary BCP-47 tags through.
• Apply conversion to text, not HTML. Running it over rendered markup corrupts tags and attributes; run it per text node or before templating.
• Because -{...}- is meaningful syntax, user content containing -{ can alter output. Escape or strip it at the boundary.

Sequencing (~4–6 weeks for a mid-size team)

1. Week 1 — Legal/license decision; dependency and provenance audit; POC of LangConv vs. OpenCC vs. ICU on 1k real strings.
2. Week 2 — Pin the package (commit SHA or exact release, no floating constraint); build the table-generation script and store the artifact; add a CI install check.
3. Weeks 3–4 — Converter adapter, Blade/API helper, variant-resolution middleware (URL prefix + Accept-Language + user preference), variant-aware cache keys.
4. Week 5 — Quality harness: golden corpus, snapshot tests, reviewer workflow, unknown-variant handling.
5. Week 6 — Canary on a low-traffic locale, then default-on.

Operational Impact

Maintenance

• Low upstream churn, but you own three things permanently: the Laravel wrapper, the table build/refresh pipeline, and the quality harness. Realistic budget is 1–2 engineer-days per quarter plus a table refresh cadence tied to MediaWiki releases.
• Pin exactly. Treat every upgrade as a deliberate, snapshot-tested event, since the upstream is Gerrit-first and you are consuming a mirror.

Support

• Community-only: Wikimedia Phabricator and MediaWiki.org docs. No vendor, no SLA, no Laravel-ecosystem familiarity. Designate two owners internally to avoid single-person dependency, and write an ADR plus a "refresh tables / add a variant" runbook.

Scaling

• Conversion is CPU-bound per string, and compiled tables are large PHP structures with meaningful per-worker memory. Under PHP-FPM, every request risks paying the load cost unless you rely on opcache/preloading or a long-lived loader; measure worker RSS with full tables loaded before sizing containers.
• At scale, do not convert per request per user. Output is deterministic, so cache rendered responses keyed by (content ID, content version, variant) — or materialize variants at write time. Either gives near-100% hit rates.

Failure modes

• Silent partial conversion — no exception, just wrong characters. Requires quality sampling in production, not just error handling.
• Markup leakage — -{...}- collisions in user content, or conversion applied to HTML instead of text.
• Cache bleed across variants — variant must be part of every cache key.
• Upgrade-induced garbling — engine/table version mismatch after a bump; mitigate with snapshot tests and canary deploys.
• Plausible-but-wrong output on names and proper nouns; irreversible without the canonical source, which is why you keep it.
• Non-idempotency — never re-convert already-converted text.
• Unknown variant code — define passthrough vs. error explicitly in the wrapper.

Ramp-up

• API surface is small; an engineer is productive in 1–2 days. The real curve is MediaWiki's variant model, fallback chains, and exception syntax — roughly 1–2 weeks to be confident. Documentation is external and sparse, so internal docs are load-bearing. Keep a Simplified/Traditional-fluent reviewer engaged for the first month.

Bottom line. Technically low-risk and battle-tested, but the decision hinges on two non-technical items: GPL-2.0 compatibility with your distribution model, and your willingness to own a conversion-table pipeline that the package deliberately does not ship. If legal clears hosted use and you can own the pipeline, adopt behind an interface with OpenCC as the documented fallback. If either fails, go straight to OpenCC and skip this dependency.