Translation and Poedit Guide

This document explains how the ADP Car Market Hub plugin handles multilingual WordPress sites, what translation files are provided with the plugin, and how to translate or update plugin strings using Poedit or equivalent tools.

When to use this document

Use this document if you are:

• Setting up the plugin on a site whose WordPress language is not English and want to confirm that translations are loaded.
• A dealer or agency adding or correcting translations for a language already included with the plugin.
• A developer contributing a new language file for a locale not yet bundled with the plugin.
• Troubleshooting plugin text that appears in English when the site language is set to another locale.

The audience is a WordPress administrator or a developer comfortable with the WordPress internationalisation workflow and basic command-line usage.

Overview

The plugin uses the standard WordPress localisation mechanism. All user-facing strings in the plugin's PHP code are wrapped in WordPress translation functions (__(), _e(), esc_html__(), and similar) with the text domain adp-car-market-hub. WordPress loads the corresponding translation file from the plugin's languages/ folder when the site language is set in Settings → General → Site Language.

The following language files are bundled with the plugin at the time of this writing:

Verify the current list by checking the languages/ directory inside the plugin folder (wp-content/plugins/adp-car-market-hub/languages/). Each locale has a .po source file (human-editable) and, where a compiled .mo file is present, that file is what WordPress actually loads at runtime.

If the site is running a locale that is not in the list above, the plugin displays all strings in the fallback language, which is English.

Prerequisites

• WordPress administrator access.
• For editing translations: Poedit (https://poedit.net/) or an equivalent .po / .mo file editor, or the Loco Translate WordPress plugin (https://wordpress.org/plugins/loco-translate/).
• For generating a new POT file: WP-CLI version 2.6 or higher, or the make-pot.sh script in bin/make-pot.sh.
• For compiling .mo files from the command line: the GNU gettext msgfmt utility, or WP-CLI's wp i18n make-mo command.

How the plugin loads translations

The plugin calls load_plugin_textdomain() on the plugins_loaded action at priority 1. This means the translation file for the current site language is loaded before any other plugin code runs at the default priority, so all admin and frontend strings are available for translation from the moment the plugin initialises.

WordPress resolves the language file in the following order:

1. wp-content/languages/plugins/adp-car-market-hub-{locale}.mo (translation files installed by WordPress itself or by a translation management tool).
2. wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-{locale}.mo (files bundled with the plugin).

Files in wp-content/languages/plugins/ take priority. If you update a bundled translation using a plugin such as Loco Translate, the updated file is typically stored at the first path, which protects your changes from being overwritten when the plugin updates.

Step by step instructions

Using an existing bundled translation

1. In WordPress, open Settings → General.
2. Set Site Language to the desired locale (for example German (Switzerland) for de_CH).
3. Save the settings.
4. Navigate to any plugin admin page or visit the frontend vehicle archive. The plugin strings (labels, buttons, error messages) should appear in the selected language.
5. If strings still appear in English, see Troubleshooting below.

Editing or correcting an existing translation with Poedit

1. Download and install Poedit from https://poedit.net/.
2. Locate the .po file for the locale you want to edit, inside the plugin's languages/ directory. For example: wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-de_CH.po.
3. Open the .po file in Poedit.
4. Find the string you want to change in the string list. The Source text column shows the English original and the Translation column shows the current translated value. Click a row to edit the translation in the editing pane below.
5. Save the file. Poedit automatically compiles the corresponding .mo file in the same directory.
6. Recommended: Copy the updated .po and .mo files to wp-content/languages/plugins/ so plugin updates do not overwrite them: - wp-content/languages/plugins/adp-car-market-hub-de_CH.po - wp-content/languages/plugins/adp-car-market-hub-de_CH.mo
7. Clear any WordPress caching that may serve stale output, then verify the change on the relevant plugin page.

Editing an existing translation with Loco Translate

1. Install and activate the Loco Translate plugin from the WordPress plugin directory.
2. In WordPress, navigate to Loco Translate → Plugins.
3. Find ADP Car Market Hub in the list and click it.
4. Select the language you want to edit.
5. Edit strings in the Loco Translate editor and save. Loco Translate compiles the .mo file automatically and stores your changes in wp-content/languages/plugins/, protecting them from plugin updates.

Creating a translation for a new language

1. Open the POT template file: wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub.pot. The POT file contains all translatable strings in the plugin without any translations.
2. In Poedit, choose File → New from POT/PO file, select the .pot file, and choose the target language.
3. Translate the strings.
4. Save as adp-car-market-hub-{locale}.po and compile to adp-car-market-hub-{locale}.mo. Use the exact locale code that WordPress uses for that language (for example fr_CH for French Switzerland). Verify the code in Settings → General → Site Language.
5. Place both files in wp-content/languages/plugins/ so they are not overwritten by plugin updates.
6. Set the site language and verify that the new translation loads correctly.

Updating translation files after a plugin update

When the plugin is updated, new strings may be added. The bundled .po files are updated by the plugin maintainers, but any custom translations stored outside the plugin directory are not automatically refreshed.

To bring your custom translation file up to date:

1. Download the updated POT file from the plugin's languages/ directory.
2. In Poedit, open your custom .po file, then choose Translation → Update from POT file and select the new .pot file. Poedit merges the new strings into your file, marking untranslated strings for attention.
3. Translate the new strings.
4. Save and compile.

If you use WP-CLI, update a .po file with msgmerge:

msgmerge --update languages/adp-car-market-hub-de_CH.po languages/adp-car-market-hub.pot

Compile the updated file:

msgfmt -o languages/adp-car-market-hub-de_CH.mo languages/adp-car-market-hub-de_CH.po

Or compile all .po files at once with WP-CLI:

wp i18n make-mo languages/

Configuration reference

There is no dedicated translation settings page in the plugin admin. Translation is handled entirely through the WordPress site language setting and the standard WordPress localisation system.

Operational notes

• Text domain. Every translatable string in the plugin uses the text domain adp-car-market-hub. This text domain is declared in the plugin header and must match the filename prefix of translation files (for example adp-car-market-hub-de_DE.mo). A mismatch between text domain and filename is the most common reason strings do not translate.
• Compiled .mo files are required at runtime. WordPress reads compiled .mo files, not the human-readable .po source files. Always compile a new or updated .po file to .mo before expecting to see changes in the browser.
• Formal vs. informal German. The de_DE_formal locale provides a formal address style (Sie) for German. Choose this locale on sites where formal phrasing is expected.
• Frontend and admin strings are both covered. The plugin's text domain includes strings for both admin pages (settings, import status, logs) and frontend output (vehicle labels, filter labels, contact form messages, financing calculator). Both sets of strings are in the same .po / .mo file.
• WordPress language packs. If the WordPress language pack system has a community translation for adp-car-market-hub for the selected locale, WordPress may offer to download it automatically. Files obtained this way are stored in wp-content/languages/plugins/ and are updated alongside WordPress core. Verify that the community translation is complete before relying on it for production.
• Caching. If translations are not appearing after a change, clear any WordPress object cache, page cache, or opcode cache. Cached bytecode of old .mo files can survive until the cache is flushed.
• Documentation files. The documentation in docs/ is written in English only. There are no translated documentation files. Translation of plugin PHP strings (as described in this guide) and translation of documentation are separate concerns.

Troubleshooting

Related documents

• Installation Guide
• First Setup
• Go Live Checklist
• Staging to Live Migration
• Theme Integration