hyperf/docs/en/translation.md

I18n

Hyperf's internationalization support is very friendly, allowing your project to support multiple languages.

Install

composer require hyperf/translation

This component is an independent component with no framework-related dependencies, and can be independently reused for other projects or frameworks.

Language file

The language files of Hyperf are placed under storage/languages by default, you can also change the folder of language files in config/autoload/translation.php, each language corresponds to a subfolder, such as en refers to the English language file, zh_CN refers to the simplified Chinese language file, you can create a new language folder and the language file in it according to your actual needs. An example is as follows:

/storage
    /languages
        /en
            messages.php
        /zh_CN
            messages.php

All language files return an array whose keys are strings:

<?php
// storage/languages/en/messages.php

return [
    'welcome' => 'Welcome to our application',
];

Configure locale

Configure default locale

The relevant configuration of the internationalization component is set in the config/autoload/translation.php configuration file, you can modify it according to your actual needs.

<?php
// config/autoload/translation.php

return [
    // default language
    'locale' => 'zh_CN',
    // Fallback language, when the language text of the default language is not provided, the corresponding language text of the fallback language will be used
    'fallback_locale' => 'en',
    // Folder where language files are stored
    'path' => BASE_PATH . '/storage/languages',
];

Configure a temporary locale

<?php

use Hyperf\Di\Annotation\Inject;
use Hyperf\Contract\TranslatorInterface;

class FooController
{
    #[Inject]
    private TranslatorInterface $translator;
    
    public function index()
    {
        // Only valid for the current request or coroutine lifetime
        $this->translator->setLocale('zh_CN');
    }
}

Translate string

Translate via TranslatorInterface

String translation can be done directly by injecting Hyperf\Contact\TranslatorInterface and calling the instance's trans method:

<?php

use Hyperf\Di\Annotation\Inject;
use Hyperf\Contract\TranslatorInterface;

class FooController
{
    #[Inject]
    private TranslatorInterface $translator;
    
    public function index()
    {
        return $this->translator->trans('messages.welcome', [], 'zh_CN');
    }
}

Translate via global function

You can also translate strings through the global functions __() or trans(). The first parameter of the function takes the form of key (referring to the key using the translation string as the key) or file.key.

echo __('messages.welcome');
echo trans('messages.welcome');

Define placeholders in translation strings

You can also define placeholders in language strings, all placeholders are prefixed with :. For example, using the username as a placeholder:

<?php
// storage/languages/en/messages.php

return [
    'welcome' => 'Welcome :name',
];

Replace the placeholder using the second parameter of the function:

echo __('messages.welcome', ['name' => 'Hyperf']);

If the placeholder is all capital letters, or the first letter is capitalized. Then the translated string will also be in the corresponding uppercase form:

'welcome' => 'Welcome, :NAME', // Welcome, HYPERF
'goodbye' => 'Goodbye, :Name', // Goodbye, Hyperf

Handle complex numbers

Plural rules are different in different languages, which may not be of great concern in Chinese, but when translating other languages, we need to deal with plural forms of words. We can use the "pipe" character, which can be used to distinguish singular and plural forms of strings:

'apples' => 'There is one apple|There are many apples',

You can also specify a range of numbers to create more complex plural rules:

'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',

Using the "pipe" character, once the plural rules have been defined, the global function trans_choice can be used to obtain a string literal for a given "amount". In the following example, since the number is greater than 1, the plural form of the translation string is returned:

echo trans_choice('messages.apples', 10);

Of course, in addition to the global function trans_choice(), you can also use the transChoice method of Hyperf\Contract\TranslatorInterface.