Localization

This page covers the localization settings in config/admin.php and how to use them.

Enabling localization

If the application needs multiple language versions, switch the parameter to true. Then run the database migration, which creates the languages table and adds the language management module to the administration.

config/admin.php

'localization' => true,

The first language added in the administration becomes the default one.

Run php artisan admin:migrate after enabling localization.

Forced redirect to the default language

Language prefixes in urls, the redirects and the helpers below: available with the crudadmin/website package (composer require crudadmin/website).

To redirect to the default language version automatically, add the middleware in bootstrap/app.php.

bootstrap/app.php

use AdminWebsite\Middleware\LocalizationMiddleware;
use Illuminate\Foundation\Configuration\Middleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(LocalizationMiddleware::class);
})

The client is redirected to the default language version on arrival — http://example.com/ redirects to http://example.com/sk. With localization active, every route is redirected to the address carrying the language code — http://example.com/articles redirects to http://example.com/sk/articles.

Disabling the forced redirect

The forced redirect can be turned off. On the default language version, every URL is then available without the language code.

config/admin.php

'localization' => [
    'remove_default' => true,
],

With this parameter, content on the default language is available only without the language code — http://example.com/articles instead of http://example.com/sk/articles. A different language saved in the session still redirects to its prefix.

Localized routes and URLs

localizedRoutes() registers a routes file with the language prefix, so /articles is available as /en/articles too.

bootstrap/app.php

use Illuminate\Support\Facades\Route;

->withRouting(
    using: function () {
        Route::middleware('web')->group(localizedRoutes('routes/web.php'));
    },
)

<a href="{{ localeUrl('articles') }}">Articles</a>          {{-- /en/articles --}}
<a href="{{ switchLocale($language) }}">{{ $language->name }}</a> {{-- current URL with ?_locale=de --}}

The routes file is registered once for every language: the prefixed languages first, the default language last (without a prefix when localization.remove_default is on). The routes work with php artisan route:cache and on Laravel Octane. Run route:cache again, or reload the Octane workers, after a language is added or its slug changes. When the languages can not be read (e.g. no database during a build), route:cache skips the routes with a warning. Named routes keep their names in the default language, the other languages get the slug as a prefix (front and en.front). route('front') and action() return the URL in the current language. For a URL in another language use LocalizedRoutes::withLocale():

use AdminWebsite\Routing\LocalizedRoutes;

$url = LocalizedRoutes::withLocale('en', fn () => route('front')); // /en/...

On a page of another language Route::currentRouteName() returns en.front, check the route with request()->routeIs('front', '*.front'). A project with its own URL::formatPathUsing() calls LocalizedRoutes::formatPath($path, $route) inside it.

Administration language

config/admin.php

'locale' => 'en', // default language of the administration (en, sk, cs)

'localization' => [
    'admin' => true, // administrators can switch the administration language
],

Admin::isEnabledLocalization() and Admin::isEnabledAdminLocalization() return the state of both switches.

Gettext — translating static texts

Together with the Gettext extension, CrudAdmin collects every static source text in the application and makes it translatable as .po files for PoEdit, or through the online editor in the administration.

Enabling Gettext

Enable the extension in config/admin.php.

config/admin.php

'gettext' => true,

The @gettext directive: available with the crudadmin/website package (composer require crudadmin/website).

To translate in JavaScript and Vue components on the frontend, add the library that initialises the translation functions. The @gettext blade directive handles it — place it in the main layout as the first script in the order. The system injects the translation libraries and caches them.

resources/views/layout.blade.php

        @gettext

        @vite('resources/js/app.js')
    </body>
</html>

CrudAdmin scans the directories where translatable files may live and reloads every source text on change. The scanned paths are defined in Gettext options.

After enabling Gettext, run php artisan admin:migrate to add the columns to the language table and enable editing PO and MO files.

The .PO file for translation is available for download in the administration.

Writing translations in the application

For translations to be picked up, static texts have to be written in the right form. The examples below cover both singular and plural.

PHP files

PHP files follow the standard functions from the PHP documentation.

// Singular
echo _('This is my translate');

// Plural
$count = 2;
echo sprintf(ngettext('%d car', '%d cars', $count), $count);

Blade files

Blade files are translated the same way as plain PHP.

<div>{{ _('This is my translate') }}</div>
<div>{{ sprintf(ngettext('%d car', '%d cars', $count), $count) }}</div>

JavaScript files

CrudAdmin reads translations from JavaScript files as well, through the methods of the injected library.

var a = _('This is my translate');
var b = __('This is my translate');
var c = gettext('This is my translate');

var d = n__('%d car', '%d cars', 2).replace('%d', 2);
var e = ngettext('%d car', '%d cars', 2).replace('%d', 2);

console.log(a, b, c, d, e);

Vue components

Vue components use the same JavaScript functions. They are bound into every component, so they are available globally as well as in the this constructor.

<template>
    <div>{{ _('This is my translate') }}</div>
    <div>{{ n__('%d car', '%d cars', 2).replace('%d', 2) }}</div>
    <div>{{ myTranslate() }}</div>
</template>

<script>
export default {
    methods: {
        myTranslate()
        {
            var trans1 = __('I have'),
                trans2 = n__('%d car', '%d cars', 2).replace('%d', 2),
                trans3 = this._('and'),
                trans4 = ngettext('%d wheel', '%d wheels', 4).replace('%d', 4);

            return trans1 + ' ' + trans2 + ' ' + trans3 + ' ' + trans4;
        }
    }
}
</script>

Gettext options

config/admin.php

'gettext' => [
    // Sources scanned for website translations, merged with the package defaults
    // (routes, app/Http, app/Mail, app/Notifications, app/Models, resources/views, resources/js, ...)
    'source_paths' => [
        'app/Services',
        'resources/views',
    ],

    // Sources scanned for administration translations
    'admin_source_paths' => ['app/Admin', 'app/Models'],

    // Language slugs which can not be resolved to a gettext locale automatically
    'supported_codes' => [
        'cz' => 'cs_CZ',
        'english' => 'en_GB',
    ],

    // /vendor/js/ca-translates-json.js returns translations as JSON
    'json' => true,

    // Remove translations missing in sources instead of flagging them
    'remove_missing' => true,
],

The language slug chosen in the administration is used in the URL, for example example.com/cz. Built-in codes resolve sk to sk_SK and cz to cs_CZ, five letter codes are used as they are. Register other slugs in gettext.supported_codes for translations to work.

Managing the translations

The generated interface for uploading files from PoEdit:

The online editor in the administration:

Online translation editor in the administration

The collected texts opened in PoEdit:

Download PoEdit at poedit.net.

Translating dynamic content

Once language versions and static text translations are set up, the interface for translating the dynamic content stored in the database can be generated too.

Mirrored content

With mirrored content the record exists once in the database, and each translatable column holds a value for every language. Add the locale parameter to the fields you want to translate.

app/Models/Project.php

public function fields()
{
    return [
        'name' => 'name:Project title|locale|required',
        'content' => 'name:Content|type:editor|locale',
    ];
}

The column stores a JSON object keyed by the language slug. Reading the attribute returns the value of the current language, with a fallback to the default language.

Required translations

Required rules of a locale field apply only to the default (first) language, other languages are optional. The model can choose another language, null uses the default one.

public function getDefaultLanguage()
{
    return Language::where('slug', 'en')->first();
}

Fallbacks, validation, API responses and converting existing columns are described in Translatable fields.

Records owning a language

Models like clients or notifications can remember the language of a record, e.g. to send e-mails in the language of the client. Declare a language_id field bound to languages and use the HasEntryLocales trait.

app/Models/Client.php

use Admin\Eloquent\Concerns\HasEntryLocales;

class Client extends AdminModel
{
    use HasEntryLocales;

    public function fields()
    {
        return [
            'name' => 'name:Name|required',
            'language_id' => 'name:Language|belongsTo:languages,name',
        ];
    }
}

$client->addLocale();   // fills an empty language_id with the current language
$client->saveLocale();  // updates language_id to the current language

$client->getLocale();   // language of the record, or the first language

$client->withLocale(function () use ($client) {
    $client->notify(new OrderShipped);
});

Getting started

Upgrade guide

Admin interface

Validation

Frontend

Website

Enabling localization

Forced redirect to the default language

Disabling the forced redirect

Localized routes and URLs

Administration language

Gettext — translating static texts

Enabling Gettext

Writing translations in the application

PHP files

Blade files

JavaScript files

Vue components

Gettext options

Managing the translations

Translating dynamic content

Mirrored content

Required translations

Records owning a language

​Enabling localization

​Forced redirect to the default language

​Disabling the forced redirect

​Localized routes and URLs

​Administration language

​Gettext — translating static texts

​Enabling Gettext

​Writing translations in the application

​PHP files

​Blade files

​JavaScript files

​Vue components

​Gettext options

​Managing the translations

​Translating dynamic content

​Mirrored content

​Required translations

​Records owning a language

Enabling localization

Forced redirect to the default language

Disabling the forced redirect

Localized routes and URLs

Administration language

Gettext — translating static texts

Enabling Gettext

Writing translations in the application

PHP files

Blade files

JavaScript files

Vue components

Gettext options

Managing the translations

Translating dynamic content

Mirrored content

Required translations

Records owning a language