Theme Localization

Themes can provide localization keys through files placed in the lang subdirectory of the theme's directory. These localization keys are registered automatically and can be used inside the theme contents or as backend form labels similar to plugin localization.

# Localization File Structure

Below is an example of the theme's lang directory.

├── themes
|   └── website
|       └── lang  ← Localization Directory
|           ├── en.json  ← Localization File
|           └── fr.json  ← Localization File

The localization file is a JSON file where strings use the "default" translation of the string as the key. For example, if your application has a French translation, you should create a lang/fr.json file.

{
    "I love programming.": "j'adore programmer"
}

You are also able to define code-based keys by using the complete language key in the JSON file, for example, theme.options.website_name for the acme theme can be used.

{
    "theme.options.website_name": "October CMS"
}

Language strings can be accessed in your theme files using the __() Twig function.

<!-- j'adore programmer -->
{{ __('I love programming.') }}

<!-- October CMS -->
{{ __('theme.options.website_name') }}

# Scanning for Messages

Instead of adding every localization key by hand, the theme templates can be scanned for translatable strings. The scanner inspects the markup of every layout, page and partial in the theme, collecting string literals passed to the translation functions (__(), trans(), trans_choice()) and filters (|trans, |_, |__, |trans_choice).

Language files are managed in the CMS Editor area of the admin panel, in the Languages section of the navigator. When editing a language file, click the Scan for Messages button in the toolbar and any newly discovered messages are added to the file as keys with empty translations, keeping the existing values untouched.

The same operation is available with the theme:scan artisan command, where new keys are written to the language file of the primary site locale.

php artisan theme:scan mytheme

Use the --locale option to target a different language file, or the --dry-run option to list the found messages without writing anything.

php artisan theme:scan mytheme --locale=fr --dry-run

# See Also