impulsephp/translation

Modular translation system for the ImpulsePHP framework with multilingual support, domain based files and automatic fallback.

v1.0.0-beta 2025-08-03 09:31 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpunit/phpunit: ^10

MIT

• Guillaume Bouyer

README

impulsephp/translation fournit le système de traduction d’ImpulsePHP. Le package charge des fichiers de langue par domaine, gère plusieurs locales et applique automatiquement un fallback vers l’anglais lorsque la traduction demandée n’existe pas dans la langue courante.

Ce que fait le package

• charge les traductions par domaine (messages, validation, ui, etc.) ;
• sélectionne une locale active ;
• remplace les paramètres dynamiques dans les chaînes ;
• permet de déclarer des namespaces pour les traductions de packages ;
• effectue un fallback automatique sur en.

Prérequis

• PHP 8.2 ou supérieur.

Installation

composer require impulsephp/translation

Si votre application ne gère pas l’auto-découverte, enregistrez Impulse\Translation\TranslatorProvider dans votre configuration.

Structure des traductions

Par défaut, le traducteur lit les fichiers dans un dossier translations/ organisé par locale.

translations/
├── en/
│   └── messages.php
└── fr/
    └── messages.php

Exemple de fichier translations/fr/messages.php :

<?php

return [
    'hello' => 'Bonjour',
    'welcome' => 'Bienvenue {name}',
];

Exemple d’usage complet

use Impulse\Translation\Translator;

$translator = new Translator('fr');

echo $translator->trans('messages.hello');
echo $translator->trans('messages.welcome', ['name' => 'Guillaume']);

$translator->setLocale('en');
echo $translator->trans('messages.hello');

Si une clé n’existe pas en français mais existe en anglais, le package renvoie automatiquement la valeur anglaise.

Utiliser un namespace de package

$translator->addNamespace('ui', '/chemin/vers/un/package/translations');

echo $translator->trans('ui::ui.select.search_placeholder');

Détection automatique de la langue

Lorsque vous n’indiquez pas explicitement la locale au constructeur, le package tente de la déterminer dans l’ordre suivant :

1. $_GET['lang']
2. $_SESSION['lang']
3. l’en-tête HTTP_ACCEPT_LANGUAGE
4. la configuration locale
5. le fallback en

La liste des locales supportées peut être définie dans la configuration supported.

Utilisation via le conteneur

Le provider enregistre Impulse\Translation\Contract\TranslatorInterface dans le conteneur.

use Impulse\Translation\Contract\TranslatorInterface;

$translator = $container->get(TranslatorInterface::class);

Aller plus loin

impulsephp/translation s’intègre directement avec :

• impulsephp/validator pour les messages d’erreur ;
• impulsephp/ui pour les libellés des composants ;
• l’application principale via locale et supported.

Tests

composer test

Licence

MIT