Documentation · Technical Documentation

Internationalization And Poedit

This document explains how the ADP Car Market Hub plugin handles translations, where the language files live and how to update or add translations using Poedit (or any compatible gettext editor).

When to use this document

Read this document if you need to:

  • Translate the plugin into a new language.
  • Update an existing translation after the plugin is upgraded.
  • Verify which locales are bundled and how they are loaded.
  • Diagnose strings that appear untranslated in the admin or on the front-end.

Overview

The plugin uses the standard WordPress internationalisation (i18n) mechanisms:

  • All translatable strings are wrapped in gettext functions (__(), _e(), _n(), _x(), etc.) using the text domain adp-car-market-hub.
  • Translations are loaded from the languages/ folder of the plugin via load_plugin_textdomain() on plugins_loaded at priority 1, before any user-facing string is rendered.
  • A POT template (adp-car-market-hub.pot) is shipped with the plugin and can be opened or regenerated with Poedit or WP-CLI.

The text domain matches the plugin folder slug (adp-car-market-hub) so translations from translate.wordpress.org style toolchains are picked up automatically when delivered to the standard locations.

Files in languages/

The bundled languages/ folder contains:

  • adp-car-market-hub.pot — translation template generated by WP-CLI's i18n make-pot (visible in the POT header).
  • adp-car-market-hub-de_DE.po — German (Germany).
  • adp-car-market-hub-de_DE_formal.po / adp-car-market-hub-de_DE_formal.mo — German (formal).
  • adp-car-market-hub-de_AT.po — German (Austria).
  • adp-car-market-hub-de_CH.po — German (Switzerland).
  • adp-car-market-hub-fr_FR.po — French (France).
  • adp-car-market-hub-it_IT.po — Italian (Italy).

Verify the exact list of .po and .mo files in the current plugin version before publishing customer-facing copy. WordPress loads the .mo file matching the active site locale; .po files alone are not sufficient at runtime.

Requirements or prerequisites

  • A gettext editor — Poedit is the recommended GUI tool. The free edition is sufficient.
  • Optional: WP-CLI with the i18n command, used to regenerate the POT file from source.
  • Write access to the languages/ folder of the plugin (or an override location, see below).

Step by step instructions

Translate into a new locale

  1. Open Poedit and choose File → New from POT/PO file.
  2. Select languages/adp-car-market-hub.pot.
  3. Pick the target locale. Save the file as adp-car-market-hub-<locale>.po inside the same languages/ folder, where <locale> is the WordPress locale code (for example es_ES, nl_NL).
  4. Translate the strings in the editor.
  5. Save. Poedit automatically writes a matching .mo file alongside the .po file.
  6. Set the WordPress site language to your new locale and reload the admin and front-end pages to verify the translations.

Update an existing translation after a plugin upgrade

  1. Open the existing .po file in Poedit.
  2. Choose Catalog → Update from POT file and select the new adp-car-market-hub.pot.
  3. Translate any new or modified strings (Poedit highlights them as untranslated or fuzzy).
  4. Save. The .mo file is regenerated automatically.

Regenerate the POT template from source (optional)

If you maintain the plugin source and need to refresh the POT yourself, you can do so with WP-CLI:

wp i18n make-pot . languages/adp-car-market-hub.pot --domain=adp-car-market-hub

Run this from the plugin's root directory. The file header records the WP-CLI version that produced it.

Use translations from outside the plugin folder

WordPress also looks for translations in wp-content/languages/plugins/adp-car-market-hub-<locale>.mo. Place a custom .mo file there if you want translations to survive plugin upgrades that overwrite languages/.

Operational notes

  • The text domain is loaded at plugins_loaded priority 1, which is intentionally before the plugin's main init() callback runs at the default priority. This ensures that every translatable string registered later already has access to the loaded .mo file.
  • Always re-save the .po file with Poedit (or compile the .mo file with msgfmt) after editing — WordPress reads the binary .mo file at runtime, not the textual .po file.
  • Locale codes are case-sensitive on case-sensitive file systems. Use the exact WordPress locale identifier.
  • Translation updates should not modify any source files; this documentation task explicitly excludes them.
  • Some strings (for example provider model identifiers in the AI Assistant or technical option labels) are intentionally kept in English. Translate user-facing copy and leave identifiers untouched.

Troubleshooting

  • A string still appears in English — confirm a .mo file for the active locale exists in languages/ (or in wp-content/languages/plugins/), the file matches the plugin's text domain (adp-car-market-hub), and your WordPress site language is set correctly.
  • A new translation does not load until cache is cleared — some object-cache plugins cache translations. Flush the WordPress object cache after deploying new .mo files.
  • Poedit shows many fuzzy strings after an update — this is expected when the source text changes. Review each fuzzy entry, correct the translation, and unmark it as fuzzy.
  • Custom translations are overwritten by plugin updates — store custom translations in wp-content/languages/plugins/ instead of the plugin's languages/ folder.