Internationalisering voor ontwikkelaars

Dit document beschrijft hoe de ADP Car Market Hub plugin omgaat met internationalisering (i18n) voor vertalers en bijdragers. Het behandelt het text domain, het laadmechanisme, de vertaalbestanden die met de plugin worden meegeleverd, de tools die worden gebruikt om het POT-bestand te genereren en de conventies die moeten worden gevolgd bij het toevoegen van nieuwe vertaalbare strings.

Wanneer u dit document moet gebruiken

Lees dit document wanneer u:

• Een nieuwe vertaalbare string wilt toevoegen aan PHP-, JavaScript- of templatecode.
• Het POT-bestand opnieuw wilt genereren na het toevoegen van strings.
• Een nieuwe taalvertaling voor de plugin wilt aanleveren.
• Wilt begrijpen waarom een specifieke string in de admin of frontend wel of niet is vertaald.

Voor opmerkingen gericht op vertalers, zie de README-i18n.md van de repository.

Overzicht

De plugin maakt gebruik van de standaard WordPress i18n-API's (__(), _e(), _n(), _x(), esc_html__(), esc_attr__(), esc_html_e(), esc_attr_e(), …) met een enkel text domain.

• Text domain: adp-car-market-hub.
• Domain path: /languages (gedeclareerd in de plugin-header).
• Loader: load_plugin_textdomain( 'adp-car-market-hub', false, '/languages' ) wordt aangeroepen vanuit een functie die is gekoppeld aan plugins_loaded met prioriteit 1, zodat vertalingen worden geladen voordat het eigen init werk van de plugin wordt uitgevoerd.

JavaScript-strings die worden gebruikt door de gebundelde scripts van de plugin, worden vooraf vertaald in PHP en doorgegeven aan JavaScript via wp_localize_script(). De plugin maakt momenteel geen gebruik van wp_set_script_translations() en de bijbehorende JSON-vertaalwerkstroom.

Vereisten of randvoorwaarden

• Bronbestanden geschreven met de WordPress i18n-functies met 'adp-car-market-hub' als het text domain.
• WP-CLI geïnstalleerd bij het opnieuw genereren van het POT-bestand (het hulpscript gebruikt wp i18n make-pot).
• Een POEdit-compatibele editor (of een andere tool die GNU gettext begrijpt) voor het bewerken van .po-bestanden.

Vertaalbestanden meegeleverd met de plugin

Alle vertaalbestanden bevinden zich onder /languages en volgen de standaard WordPress naamgevingsconventie.

Elke meegeleverde locale bevat zowel een .po-bronbestand als een gecompileerd .mo-bestand. De bovenstaande lijst weerspiegelt de bestanden die momenteel aanwezig zijn; controleer de meest recente set in de map /languages voordat u publiceert.

Tooling

Het POT-bestand opnieuw genereren

Er is een hulpscript beschikbaar in de map bin/ van de repository. Dit script roept het i18n make-pot-commando van WP-CLI aan en sluit mappen uit die niet gescand mogen worden (.git, node_modules, vendor, tests, bin).

Om het uit te voeren:

1. Zorg ervoor dat WP-CLI is geïnstalleerd en beschikbaar is op PATH.
2. Voer het script uit vanuit de root van de repository.
3. Het bijgewerkte .pot-bestand wordt weggeschreven naar languages/adp-car-market-hub.pot.

.mo-bestanden compileren

Na het bewerken van een .po-bestand compileert u een bijbehorend .mo-bestand met uw editor (de "Opslaan"-functie van POEdit produceert beide bestanden automatisch) of met msgfmt van gettext.

Stapsgewijze instructies

Een vertaalbare string toevoegen in PHP

1. Omhul de string met de juiste WordPress i18n-functie en geef 'adp-car-market-hub' op als het text domain. Bijvoorbeeld __( 'Lead saved.', 'adp-car-market-hub' ) of esc_html__( 'Vehicles', 'adp-car-market-hub' ).
2. Waar de string wordt samengevoegd met HTML, verdient het de voorkeur om de varianten esc_*__ en esc_*_e te gebruiken om escaping en vertaling in één aanroep te combineren.
3. Gebruik voor meervoudsvormen _n() of _nx(). Gebruik voor contextuele verduidelijking _x().
4. Genereer het POT-bestand opnieuw (zie hierboven) zodat vertalers de nieuwe string kunnen oppakken.

Een vertaalbare string toevoegen die in JavaScript wordt gebruikt

1. Vertaal de string eerst in PHP (__( 'Sending…', 'adp-car-market-hub' )).
2. Geef deze door aan JavaScript via de wp_localize_script()-array die wordt gebruikt door de relevante handle. Zie Frontend Assets en Admin Assets voor de gelokaliseerde objecten die al in gebruik zijn (bijvoorbeeld AS24CI, as24ciCompare, AS24CI_LEADS, AS24CI_BATCH).
3. Lees de waarde uit de bijbehorende globale variabele in de JavaScript-code.

Een nieuwe vertaling aanleveren

1. Kopieer languages/adp-car-market-hub.pot naar languages/adp-car-market-hub-<locale>.po met behulp van de WordPress-landcode (bijvoorbeeld es_ES).
2. Vertaal de strings.
3. Compileer het .mo-bestand samen met het .po-bestand.
4. Open een pull request met beide bestanden.

Operationele opmerkingen

• Enkel text domain. Elke vertaalbare string in de plugin gebruikt 'adp-car-market-hub'. Introduceer geen extra text domains.
• Houd de POT actueel. Wanneer een bijdrager strings toevoegt of verwijdert, genereer dan het POT-bestand opnieuw in dezelfde wijziging, zodat vertaalbestanden netjes kunnen worden samengevoegd.
• JavaScript-strings. Omdat JS-strings worden vertaald via wp_localize_script(), verschijnen ze alleen in de POT wanneer de bijbehorende PHP-aanroep __() aanwezig is. Vertaal JS-strings altijd eerst in PHP.
• Regiospecifieke opmaak. Getal- en valutaopmaak wordt afgehandeld door de eigen locale-helpers van de plugin. Gebruik de helpers die door de plugin worden aangeboden in plaats van de locale-logica opnieuw te implementeren in uw eigen code.
• WordPress vertaalplatform. De plugin kan buiten de repository worden vertaald via elke standaard gettext-werkstroom. Er is geen specifieke externe vertaalservice vereist.

Probleemoplossing

• Een string is niet vertaald op de frontend. Controleer of de string is omhuld met een i18n-functie met het juiste text domain. Controleer of de taal is geïnstalleerd in WordPress (Instellingen → Algemeen → Websitetaal) en of er een .mo-bestand voor die locale bestaat in /languages.
• Nieuw toegevoegde strings verschijnen niet in de POT. Voer het POT-hulpscript opnieuw uit. Controleer of uw bestand zich niet in een van de uitgesloten mappen bevindt.
• Tekst aan de JS-zijde is nog steeds in het Engels na PHP-vertaling. Controleer of de string wordt doorgegeven via wp_localize_script() voor de relevante handle. De plugin detecteert niet automatisch onvertaalde JS-strings.
• Meervoudsvormen vallen terug op het enkelvoud. Gebruik _n() (of _nx() voor context) in plaats van __() voor elke string die varieert op basis van een aantal.
• Verifieer het gedrag in de huidige plugin-versie voordat u een aangepaste integratie publiceert. Gelokaliseerde JavaScript-objectnamen kunnen tussen releases veranderen.

Gerelateerde documenten

• Frontend Assets
• Admin Assets
• Coding Standards
• Repository Structure
• Contribution Guidelines