Skip to content

Update Connector Widget Translations

Use this guide when you need to change existing copy, fix a translation, or add a new string or locale to the connector widget (<conflux-connector>). For how translation resolution, fallback, and inline-HTML sanitisation work, see Connector Widget → Localisation.

Source of truth

Translation content lives in the "Conflux_Widgets_translations_MERGED" Google Sheet (https://docs.google.com/spreadsheets/d/1hMeswv5GBmIivDb37chDuNy8l1OWAg4qGYP7QSlb9NU/edit), not hand-typed in this repository. Edit the string there first — resources/widget-connector/i18n.js has no hand-maintained translation content of its own; every key it exposes comes straight from a sheet row via resources/widget-connector/translations-source.json (generated — do not hand-edit).

There is no overrides layer to keep in sync. A string that doesn't exist in the sheet yet simply renders as its own key name in the widget (e.g. a missing widget_copy_cta row shows the literal text "widget_copy_cta") until a matching row is added — that's the fallback, by design, so a gap is obvious rather than silently patched with made-up copy.

1. Update the sheet, then regenerate

Getting a fresh export of the sheet into translations-source.json depends on how you're working:

If you're Claude Code with the Google Drive MCP connector available: fetch it directly, no manual download needed:

  1. Call mcp__claude_ai_Google_Drive__download_file_content with fileId: "1hMeswv5GBmIivDb37chDuNy8l1OWAg4qGYP7QSlb9NU" and exportMimeType: "text/csv" — returns base64-encoded CSV.
  2. Decode it and write it to a file inside the repo (docker compose run node only mounts the repo — a scratchpad or other path outside it isn't visible to the container).
  3. Run the generator against that file (step 2 below), then delete the temp CSV — only translations-source.json gets committed, not the CSV.

Otherwise (manual export): in the sheet, File → Download → Comma Separated Values, saved as a single .csv file at the repo root (or anywhere — pass the path explicitly).

Then, either way, regenerate the JSON:

docker compose run --rm -T node npm run widget:translations
# or, with an explicit path:
docker compose run --rm -T node node scripts/generate-widget-translations.mjs path/to/export.csv

Review the diff on translations-source.json — it's checked into git specifically so sheet changes show up in code review like any other content change. No further hand-editing is needed: i18n.js picks up the new content automatically on the next rebuild.

For a brand-new string, add a row to the sheet with a Token value matching the key ConfluxConnector.vue calls via t(key, vars) — see ConfluxConnector.vue for existing key names (e.g. step1_title_woocommerce) and their {placeholder} usage as a naming reference.

Placeholders

Strings support {placeholder} interpolation, substituted by the vars object passed at the t() call site in ConfluxConnector.vue. Keep placeholder names identical across all locales — the calling code passes the same vars regardless of locale.

Bold or emphasised text

Only bare <strong> and <em> tags are allowed inline — no attributes, no other tags — anything else is escaped and rendered as literal text. Add them directly in the sheet cell wherever the bold/emphasised phrase falls in that language's word order (which can differ from English):

Click on "<strong>Get the {connector_name} plugin</strong>" below to install it on your {system} store:

There's no code-side bolding mechanism — if a string should be bold, the sheet cell needs the tag.

2. Adding a new locale

  1. Confirm the sheet has a column for it, then export and regenerate per step 1 above.
  2. Add the locale code to SUPPORTED_LOCALES in resources/widget-connector/i18n.js, and to LOCALE_COLUMNS in scripts/generate-widget-translations.mjs (mapping the locale code to the sheet's column header), then re-run the generator.
  3. Add an <option> for it to the "Widget language" select in resources/views/examples/connection-widget.blade.php so it can be previewed locally.
  4. Update tests/Feature/ConnectionWidgetExampleTest.php to expect the new option.
  5. Update the supported-locale list in the Embed the Connector Widget lang prop row.

3. Rebuild the widget

Translation strings are baked into the bundle at build time:

docker compose run --rm -T node npm run build:connector-widget

4. Preview

Visit /examples/connection-widget and use the "Widget language" selector in Step 1 to switch the mounted <conflux-connector> element between locales without leaving the page.

Test

tests/Feature/ConnectionWidgetExampleTest.php asserts the demo page renders and lists all six locale options. Update it if you add or remove a supported locale.

docker compose exec php php artisan test --compact --filter ConnectionWidgetExampleTest

See also