Rainlab Translate Plugin

https://github.com/rainlab/translate-plugin
Admin
A plugin for October CMS that enables multi-lingual sites by providing features for language...
Tokens:35,472
Snippets:554
Trust Score:7.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Fresh Installation Workflow

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Sequence of commands to initialize the plugin after a fresh installation.

```bash
# 1. Install plugin
php artisan plugin:install rainlab.translate

# 2. Configure sites in backend
# Settings → Sites (create sites for each locale)

# 3. Scan and import messages
php artisan translate:scan

# 4. Clear cache
php artisan cache:clear

# 5. Access in backend
# Settings → Translate Messages
```

--------------------------------

### Install RainLab Translate Plugin

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Standard command to install the plugin via artisan. Database migrations run automatically upon installation.

```bash
# Install plugin
php artisan plugin:install rainlab.translate

# No migration command needed - runs automatically
# Tables created:
# - rainlab_translate_message_data
# - rainlab_translate_attributes
# - rainlab_translate_indexes
```

--------------------------------

### Install Translate Plugin

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Command to install the RainLab Translate plugin if the translate namespace is missing.

```bash
php artisan plugin:install rainlab.translate
```

--------------------------------

### Multi-Site Locale Configuration

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Examples of mapping sites to specific locales and domains.

```text
Site 1: locale = 'en', domain = example.com
Site 2: locale = 'fr', domain = example.fr
Site 3: locale = 'de', domain = example.de
```

```text
Site 1: locale = 'en', domain = example.com
Site 2: locale = 'en', domain = example-us.com
Site 3: locale = 'fr', domain = example.fr (primary for French)
```

--------------------------------

### Install RainLab Translate Plugin

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/INDEX.md

Use these commands to install the plugin based on your October CMS version.

```bash
# For October CMS v3.1+
php artisan plugin:install rainlab.translate

# For October CMS v3.0 and below
php artisan plugin:install rainlab.translate --want="^1.0"
```

--------------------------------

### Raw SQL Queries

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-attribute-model.md

SQL examples for inspecting the rainlab_translate_attributes table structure and content.

```sql
-- Get all German translations of Posts
SELECT * FROM rainlab_translate_attributes
WHERE model_type = 'App\Models\Post'
  AND locale = 'de'
LIMIT 10;

-- Check data
SELECT 
    model_id,
    locale,
    attribute_data
FROM rainlab_translate_attributes
WHERE model_type = 'App\Models\Post'
  AND model_id = 1
ORDER BY locale;

-- Count translations per model
SELECT 
    model_type,
    COUNT(*) as translation_count
FROM rainlab_translate_attributes
GROUP BY model_type
ORDER BY translation_count DESC;
```

--------------------------------

### Define theme translation configuration

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Examples of how to define translatable messages within theme.yaml.

```yaml
translate:
    en:
        key: value
```

```yaml
translate: config/lang.yaml
```

```yaml
translate:
    en: config/lang-en.yaml
    fr: config/lang-fr.yaml
```

--------------------------------

### isConfigured()

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translator.md

Checks if the Translate plugin is installed, database is available, and configured.

```APIDOC
## isConfigured()

### Description
Checks if the Translate plugin is installed, database is available, and configured. Result is cached in the session for efficiency.

### Returns
- **bool** - true if plugin is ready to use, false otherwise.
```

--------------------------------

### Event Registry Usage Examples

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-event-registry.md

Demonstrates manual event registration and common event listeners for theme scanning, URL overriding, and mail template customization.

```php
use RainLab\Translate\Classes\EventCoreRegistry;

// Manually trigger event registration
$registry = EventCoreRegistry::instance();
$registry->registerEvents();
$registry->bootEvents();

// Listen to theme scanner completion
Event::listen('rainlab.translate.themeScanner.afterScan', function ($scanner) {
    // Process scan results
});

// Override page URL for a locale
Event::listen('cms.sitePicker.overridePattern', function ($page, $pattern, $old, $new) {
    if ($page->baseFileName == 'contact') {
        return '/kontakt';  // German URL
    }
});

// Customize mail template localization
Event::listen('mailer.beforeAddContent', function ($mailer, $message, $view, $data) {
    // Custom template loading logic
});
```

--------------------------------

### Twig Cache Key Examples

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-cms-object.md

Shows how cache keys are automatically suffixed with the locale to prevent cross-contamination.

```text
// Default (English): contact-page-abc123
// French:            contact-page-abc123-fr
// German:            contact-page-abc123-de
```

--------------------------------

### Check Plugin Configuration

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translator.md

Verifies if the Translate plugin is installed and properly configured, using session caching for performance.

```php
if ($translator->isConfigured()) {
    // Safe to use translation features
}
```

--------------------------------

### View translate:scan output

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Example console output after running the scan command with the purge option.

```text
Purging messages...
Messages scanned successfully.
Note: You may need to run cache:clear for updated messages to take effect.
```

--------------------------------

### Get all locales as array in PHP

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-locale.md

Returns all locale definitions as a flattened array.

```php
$all = Locale::all();
// Returns: [Locale(code=en), Locale(code=fr), Locale(code=de)]
```

--------------------------------

### Retrieve Translated Model Instance

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-attribute-model.md

Example of fetching an attribute record and accessing the associated model instance.

```php
$attr = Attribute::first();

// Get the translated model
$post = $attr->model;  // Post instance
echo $post->title;

// Check model type
if ($attr->model_type === 'App\Models\Post') {
    // It's a Post model translation
}
```

--------------------------------

### Implement Language Picker Component

Source: https://github.com/rainlab/translate-plugin/blob/master/README.md

Examples of using the SitePicker component to create language selection interfaces in Twig.

```twig
title = "Home"
url = "/"

[sitePicker]
==

<h3>{{ 'Please select your language:'|_ }}</h3>
<select class="form-control" onchange="window.location.assign(this.value)">
    {% for site in sitePicker.sites %}
        <option value="{{ site.url }}" {{ this.site.code == site.code ? 'selected' }}>{{ site.name }}</option>
    {% endfor %}
</select>
```

```twig
<p>
    Switch language to:

    {% for site in sitePicker.sites %}
        <a href="{{ site.url }}">{{ site.name }}</a>
    {% endfor %}
</p>
```

--------------------------------

### Check translation requirement

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Method signature and usage example for determining if the current context requires translation.

```php
public function shouldTranslate(): bool
```

```php
if ($behavior->shouldTranslate()) {
    // We're in a non-default language
}
```

--------------------------------

### Silent Message Observer Exception Handling

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/errors.md

Used in Message::saveObserver to prevent installation failures when database tables do not yet exist.

```php
try {
    // Save observed messages
} catch (Exception $ex) {
    // Silently swallow - database may not exist yet
}
```

--------------------------------

### Get current site locale in PHP

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-locale.md

Retrieves the locale of the currently active site context.

```php
$current = Locale::getSiteLocaleFromContext(); // Current request's locale
```

--------------------------------

### Get Current Path in Locale

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translator.md

Generates the current request path prefixed with the specified locale code.

```php
$path = $translator->getCurrentPathInLocale('de');
// If current path is /contact, returns /de/contact
```

--------------------------------

### Message Record Data Structure

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/types.md

Example JSON structure for message data and usage tracking in the rainlab_translate_message_data table.

```json
{
  "data": {
    "welcome": "Welcome",
    "goodbye": "Goodbye",
    "menu.home": "Home"
  },
  "usage": {
    "welcome": 1626432000,
    "goodbye": 1626518400
  }
}
```

--------------------------------

### Get Default Locale

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translator.md

Retrieves the primary locale configured for the site.

```php
$default = $translator->getDefaultLocale(); // e.g., 'en'
```

--------------------------------

### Run Migration Command

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Executes the migration process to convert v1 translation data to the v2 format.

```bash
php artisan translate:migratev1
```

--------------------------------

### Upgrade from v1

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Workflow for migrating data when upgrading from version 1 of the plugin.

```bash
# 1. Install plugin (if upgrading code version)
php artisan plugin:update rainlab.translate

# 2. Run migration
php artisan translate:migratev1

# 3. Verify messages
php artisan translate:scan

# 4. Clear cache
php artisan cache:clear
```

--------------------------------

### Get Translated Attribute

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-page.md

Fetches a translated value from the viewBag for a given key and locale.

```php
public function getAttributeTranslated(string $key, string|null $locale = null): string
```

```php
// Internal storage location:
// viewBag.localeTitle.fr = "Titre"
// viewBag.localeDescription.de = "Beschreibung"

$title = $page->getAttributeTranslated('title', 'fr');  // "Titre"
$desc = $page->getAttributeTranslated('settings[description]', 'de');  // "Beschreibung"
```

--------------------------------

### Database Permission Troubleshooting

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Configuration check for database user privileges when encountering permission errors.

```bash
# Check database credentials in .env
# Ensure user has CREATE, ALTER, DROP privileges
```

--------------------------------

### Get modified locales

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Returns a list of locale codes that contain unsaved changes.

```php
public function getDirtyLocales(): array
```

--------------------------------

### Scan and Import Messages

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/INDEX.md

Run this command after configuring sites to scan and import messages into the system.

```bash
# Configure sites in Settings → Sites
# Scan and import messages
php artisan translate:scan
```

--------------------------------

### Verify plugin configuration

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/errors.md

Checks if the database is available and the required translation tables exist.

```php
if (App::hasDatabase() && Schema::hasTable('rainlab_translate_locales')) {
    return true;
}
```

```php
if (!Translator::instance()->isConfigured()) {
    // Plugin not fully configured, skip translations
}
```

--------------------------------

### Initialize Translation Context

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-page.md

Sets up the translation context and caches original attribute values.

```php
public function initTranslatableContext(): void
```

--------------------------------

### translateContext(string|null $context = null)

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Gets or sets the active translation context (locale) for the model.

```APIDOC
## translateContext(string|null $context = null)

### Description
Gets or sets the active translation context (locale). If no parameter is provided, it returns the current locale.

### Parameters
- **context** (string|null) - Optional - Locale to set; if null, returns current.

### Returns
- (string|void) - Current context if parameter is null; void if setting.
```

--------------------------------

### Execute translate:scan artisan commands

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Run theme scanning via the command line with optional purging of old messages.

```bash
# Scan and import messages
php artisan translate:scan

# Scan, purge old messages, then import
php artisan translate:scan --purge
```

--------------------------------

### Get original translated values

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Returns the original values of translated attributes for a given locale.

```php
public function getTranslatableOriginals(string|null $locale = null): array|null
```

--------------------------------

### Get dirty translated attributes

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Retrieves an array of attributes and their values that have been modified in a specific locale.

```php
public function getTranslateDirty(string|null $locale = null): array
```

--------------------------------

### Manage and Retrieve Locales in PHP

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-locale.md

Demonstrates common operations such as listing locales, checking availability, finding specific locales, and managing user locale selection.

```php
use RainLab\Translate\Classes\Locale;

// Check if translations are configured
if (!Locale::isAvailable()) {
    return;  // Only one language configured
}

// Get all locales
$allLocales = Locale::listLocales();
foreach ($allLocales as $locale) {
    echo "{$locale->code}: {$locale->name}";
}

// Get enabled locales for frontend
$frontendLocales = Locale::listEnabled();
// Use in language picker dropdown

// Get specific locale
$french = Locale::findByCode('fr');
if ($french) {
    echo $french->name;  // 'Français'
}

// Validate user input
$userLocale = request()->input('locale');
if (Locale::isValid($userLocale)) {
    $translator->setLocale($userLocale);
}

// Get default locale
$default = Locale::getDefault();
echo $default->code;  // 'en'

// Backend vs Frontend
$backendLocales = Locale::listAvailable();    // All configured
$frontendLocales = Locale::listEnabled();     // Only enabled ones
```

--------------------------------

### Get Active Locale

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translator.md

Retrieves the currently active locale, with an option to prioritize the session-stored value.

```php
$locale = $translator->getLocale(); // Returns currently active locale
$locale = $translator->getLocale(true); // Returns session-stored locale if available
```

--------------------------------

### ThemeScanner::scan()

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Static convenience method to run a complete theme scan, creating a new instance and firing the afterScan event.

```APIDOC
## ThemeScanner::scan()

### Description
Creates a new ThemeScanner instance, runs scanForMessages(), and fires the rainlab.translate.themeScanner.afterScan event.

### Signature
`public static function scan(): self`

### Returns
- **ThemeScanner** - The scanner instance for method chaining.
```

--------------------------------

### EventCoreRegistry::bootEvents

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-event-registry.md

Manually triggers the booting of events within the plugin.

```APIDOC
## bootEvents

### Description
Manually triggers the booting of events for the plugin.

### Signature
`public function bootEvents(): void`
```

--------------------------------

### Translatable Attribute Data Structure

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/types.md

Example JSON structure for the attribute_data field in the rainlab_translate_attributes table.

```json
{
  "title": "Titre Français",
  "content": "Contenu en français",
  "slug": "titre-francais"
}
```

--------------------------------

### Initialize TranslatableModel

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-model.md

Constructor for the behavior, setting up morphMany relations and event listeners.

```php
public function __construct($model)
```

--------------------------------

### Scan and Purge Translation Messages

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Examples for scanning messages with or without purging existing data.

```bash
# Scan and merge with existing messages
php artisan translate:scan

# Purge old messages and import fresh
php artisan translate:scan --purge
```

--------------------------------

### Set translated attribute

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Method signature and usage example for setting a translated attribute value.

```php
public function setAttributeTranslated(string $key, mixed $value, string|null $locale = null): mixed
```

```php
$user = User::first();
$user->translateContext('fr');
$user->setAttributeTranslated('name', 'Jean-Claude');
$user->save();
```

--------------------------------

### Deployment CLI Commands

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Commands for scanning theme messages and clearing cache during deployment cycles.

```bash
# Scan for new messages in theme
php artisan translate:scan

# Clear cache
php artisan cache:clear
```

```bash
# Scan and import any new messages
php artisan translate:scan

# Purge removed messages and import fresh
php artisan translate:scan --purge

# Clear cache
php artisan cache:clear
```

--------------------------------

### Retrieve translated attribute

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Method signature and usage example for retrieving a translated attribute value.

```php
public function getAttributeTranslated(string $key, string|null $locale = null): mixed
```

```php
$user = User::first();
$frenchName = $user->getAttributeTranslated('name', 'fr');
```

--------------------------------

### Disable fallback locale

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Method signature and usage example for disabling fallback to the default locale.

```php
public function noFallbackLocale(): \October\Rain\Database\Model
```

```php
$user = User::first();
$user->noFallbackLocale()->lang('fr');
echo $user->name; // NULL if no French translation exists
```

--------------------------------

### Manage Locales and Paths with Translator

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translator.md

Use the Translator instance to check configuration, retrieve locale settings, switch languages, and resolve localized URLs.

```php
use RainLab\Translate\Classes\Translator;

$translator = Translator::instance();

// Check if configured
if (!$translator->isConfigured()) {
    return;
}

// Get/set locale
$current = $translator->getLocale();
$default = $translator->getDefaultLocale();

// Switch languages
if ($translator->setLocale('de')) {
    $path = $translator->getPathInLocale('/contact', 'de');
    $pageUrl = $translator->getPageInLocale('contact', 'de');
}

// Load from session
$translator->loadLocaleFromSession();
```

--------------------------------

### Get Translatable Model Class

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-cms-object.md

Returns the fully qualified class name used for handling translations.

```php
public function getTranslatableModelClass(): string
```

--------------------------------

### Handle URL Parameters and Language Selection

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/INDEX.md

Manage locale-specific URL parameters and implement custom language switching logic.

```php
cms.sitePicker.overrideParams
```

```php
Model::translateParams()
```

```php
Locale::listEnabled()
```

```twig
localeUrl()
```

--------------------------------

### Get Localized View Method Signature

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-event-registry.md

Defines the method signature for retrieving localized mail templates.

```php
public function getLocalizedView($factory, $code, $locale): string|null
```

--------------------------------

### Listen to rainlab.translate.themeScanner.afterScan

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/types.md

Event listener triggered after theme scanning completes.

```php
Event::listen('rainlab.translate.themeScanner.afterScan',
    function(ThemeScanner $scanner) {
        // $scanner - ThemeScanner instance with results
        $found = $scanner->getFoundMessages();
    }
);
```

--------------------------------

### Configure theme translations

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Define translation keys directly in theme.yaml or reference an external configuration file.

```yaml
name: My Theme
author: My Company

translate:
    en:
        site.title: My Website
        site.tagline: The best website
        menu.home: Home
        menu.about: About
    fr:
        site.title: Mon Site
        site.tagline: Le meilleur site
        menu.home: Accueil
        menu.about: À Propos
    de:
        site.title: Meine Website
        site.tagline: Die beste Website
        menu.home: Startseite
        menu.about: Über Uns
```

```yaml
name: My Theme
author: My Company

translate: config/lang.yaml
```

--------------------------------

### Run translate:scan command

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Execute the scan command via CLI to import theme messages.

```bash
php artisan translate:scan
php artisan translate:scan --purge
```

--------------------------------

### Common translate:scan workflow

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Standard CLI workflow for scanning and clearing cache.

```bash
# Initial setup - import theme messages
php artisan translate:scan

# After adding new messages to theme
php artisan translate:scan

# Full refresh - remove old, add new
php artisan translate:scan --purge

# Clear cache to see updated messages
php artisan cache:clear
```

--------------------------------

### Retrieve Plugin Metadata

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-plugin.md

Access the plugin's configuration details including name, author, and homepage.

```php
$details = $plugin->pluginDetails();
// Returns:
// [
//     'name' => 'Translate',
//     'description' => 'Enables multi-lingual websites.',
//     'author' => 'Alexey Bobkov, Samuel Georges',
//     'icon' => 'icon-language',
//     'homepage' => 'https://github.com/rainlab/translate-plugin'
// ]
```

--------------------------------

### Get page URL for locale with Twig filter

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/INDEX.md

Retrieves the URL for a specific page and locale with optional parameters.

```twig
{{ 'page'|localePage('fr', {slug: 'x'}) }}
```

--------------------------------

### Register Console Commands

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Implementation of command registration within the plugin's register method.

```php
public function register()
{
    $this->registerConsoleCommand('translate.scan', 
        \RainLab\Translate\Console\ScanCommand::class);
        
    $this->registerConsoleCommand('translate.migratev1', 
        \RainLab\Translate\Console\MigrateV1Command::class);
}
```

--------------------------------

### Get or set translation context

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Use to retrieve the current locale or switch the active translation context for a model.

```php
public function translateContext(string|null $context = null): string|void
```

```php
$user = User::first();
echo $user->translateContext(); // Current locale
$user->translateContext('fr'); // Switch to French
```

--------------------------------

### Extend Theme Scanning with Events

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Register a listener to import custom messages into the scanner after the scan completes.

```php
Event::listen('rainlab.translate.themeScanner.afterScan', function ($scanner) {
    // Add custom messages from plugin
    $scanner->importMessages([
        'plugin.feature' => 'Feature Name'
    ], 'en', true);
});
```

--------------------------------

### Boot translation events

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-event-registry.md

Enables translation-related event handlers during the plugin boot phase.

```php
public function bootEvents(): void
```

--------------------------------

### Scan and Import Theme Translations

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/guides-translation-workflow.md

Use artisan commands to discover or purge and re-import translation messages.

```bash
# Auto-discover and import messages
php artisan translate:scan

# Purge old messages and re-import fresh
php artisan translate:scan --purge
```

--------------------------------

### Scan and clear cache during deployment

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/guides-translation-workflow.md

Run these commands in your deployment script to ensure all translation messages are indexed and the cache is refreshed.

```bash
# In deployment script
php artisan translate:scan
php artisan cache:clear
```

--------------------------------

### Implement translate:scan handle method

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

The internal logic for the scan command, handling the optional purge flag and triggering the theme scanner.

```php
public function handle()
{
    if ($this->option('purge')) {
        $this->output->writeln('Purging messages...');
        Message::truncate();
    }

    ThemeScanner::scan();
    $this->output->success('Messages scanned successfully.');
    $this->output->note('You may need to run cache:clear for updated messages to take effect.');
}
```

--------------------------------

### Soft Implementation of Translatable Behavior

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Use the @ prefix to implement the TranslatableModel behavior optionally, preventing errors if the plugin is missing.

```php
class Post extends Model
{
    // Soft implement - only if plugin is installed
    public $implement = [
        '@RainLab.Translate.Behaviors.TranslatableModel'
    ];

    public $translatable = ['title'];
}
```

--------------------------------

### Define Default Messages in theme.yaml

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/guides-translation-workflow.md

Define translation strings for different locales within the theme configuration file.

```yaml
name: My Website

translate:
    en:
        site.title: My Website
        site.tagline: Welcome to our site
        menu.home: Home
        menu.about: About Us
        menu.contact: Contact
    fr:
        site.title: Mon Site
        site.tagline: Bienvenue sur notre site
        menu.home: Accueil
        menu.about: À Propos
        menu.contact: Contact
```

--------------------------------

### Define Plugin Permissions

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-plugin.md

Structure for defining backend permissions within the plugin registration.

```php
// Returns:
[
    'rainlab.translate.manage_messages' => [
        'tab' => 'Translation',
        'label' => 'Manage messages'
    ]
]
```

--------------------------------

### Add language picker component

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/guides-translation-workflow.md

Include the language picker component and render a dropdown for site switching.

```php
[languagePicker]
```

```twig
<select class="form-control" onchange="window.location.assign(this.value)">
    {% for site in languagePicker.sites %}
        <option value="{{ site.url }}" 
                {% if site.code == this.site.code %}selected{% endif %}>
            {{ site.name }}
        </option>
    {% endfor %}
</select>
```

--------------------------------

### Define translation parameters

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/guides-translation-workflow.md

Use colon-prefixed placeholders for dynamic content injection.

```text
Hello :user, welcome to :site!
```

--------------------------------

### Implement parameter translation logic in a model

Source: https://github.com/rainlab/translate-plugin/blob/master/README.md

A sample implementation of the translateParams method to map parameter values between locales using transWhere.

```php
public static function translateParams($params, $oldLocale, $newLocale)
{
    $newParams = $params;
    foreach ($params as $paramName => $paramValue) {
        $records = self::transWhere($paramName, $paramValue, $oldLocale)->first();
        if ($records) {
            $records->translateContext($newLocale);
            $newParams[$paramName] = $records->$paramName;
        }
    }
    return $newParams;
}
```

--------------------------------

### Session Configuration Keys

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Reference keys used for storing the active locale and configuration status in the session.

```php
'rainlab.translate.locale'  // Active locale
'rainlab.translate.configured'  // Configuration status
```

--------------------------------

### ThemeScanner::scanThemeConfigForMessages()

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Scans theme.yaml configuration for defined messages.

```APIDOC
## ThemeScanner::scanThemeConfigForMessages()

### Description
Looks for the 'translate' key in the theme configuration to extract language-specific messages.

### Signature
`public function scanThemeConfigForMessages(string|null $themeCode = null): void`

### Parameters
- **themeCode** (string|null) - Optional - Theme code; defaults to active theme.
```

--------------------------------

### TranslatableModel Usage

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-attribute-model.md

Demonstrates how TranslatableModel handles attribute querying and storage internally.

```php
// This internally uses Attribute model
$post = Post::first();
$post->lang('fr');
echo $post->title;  // Loaded from Attribute table

// This internally uses Attribute model
$post->title = 'Nouveau Titre';
$post->save();  // Stored in Attribute table
```

--------------------------------

### Configure theme translations in theme.yaml

Source: https://github.com/rainlab/translate-plugin/blob/master/README.md

Define default translation keys directly within the theme.yaml file.

```yaml
name: My Theme
# [...]

translate:
    en:
        site.name: 'My Website'
        nav.home: 'Home'
        nav.video: 'Video'
        title.home: 'Welcome Home'
        title.video: 'Screencast Video'
```

--------------------------------

### Scan theme for messages

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Use the static scan method to initialize a scanner, perform a full scan, and retrieve the discovered messages.

```php
$scanner = ThemeScanner::scan();
$found = $scanner->getFoundMessages();
```

--------------------------------

### Configure Locale-Specific Translation Files

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Map individual locales to separate configuration files within theme.yaml.

```yaml
name: My Theme

translate:
    en: config/lang-en.yaml
    fr: config/lang-fr.yaml
    de: config/lang-de.yaml
```

--------------------------------

### Configure Translatable Theme Properties

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-event-registry.md

Enable translation for theme customization fields by setting the translatable property to true in theme.yaml.

```yaml
properties:
    website_name:
        label: Website Name
        type: text
        translatable: true
```

--------------------------------

### Listen to afterScan event

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Hook into the theme scanning process to perform custom logic after messages are discovered.

```php
Event::listen('rainlab.translate.themeScanner.afterScan', function (ThemeScanner $scanner) {
    // Custom scanning logic
    $found = $scanner->getFoundMessages();
});
```

--------------------------------

### lang(string|null $context = null)

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Shorthand for translateContext() that is chainable.

```APIDOC
## lang(string|null $context = null)

### Description
Shorthand for `translateContext()`, allowing for method chaining on the model.

### Parameters
- **context** (string|null) - Optional - Locale to set.

### Returns
- (\October\Rain\Database\Model) - The extended model instance.
```

--------------------------------

### Retrieve translatable attributes with options

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Returns an array mapping attribute names to their specific configuration options.

```php
public function getTranslatableAttributesWithOptions(): array
```

```php
// For $translatable = ['name', ['slug', 'index' => true]]
// Returns: ['slug' => ['index' => true]]
```

--------------------------------

### Configure Translatable File Attachments

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/types.md

Defines translatable file attachments in a model and demonstrates how to access them by locale.

```php
class Product extends Model
{
    public $translatable = ['image'];
    public $attachOne = ['image' => 'System\Models\File'];
}

// Access per locale
$product->lang('en')->image; // English version
$product->lang('fr')->image; // French version
```

--------------------------------

### Model Translation Operations in PHP

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-model.md

Demonstrates common translation tasks such as setting locale-specific attributes, querying, sorting, and checking for existing translations.

```php
// Basic translation
$post = Post::first();
$post->title = 'English Title';

$post->lang('fr');
$post->title = 'Titre Français';
$post->save();

// Retrieve translations
$post = Post::first();
echo $post->lang('en')->title;  // English Title
echo $post->lang('fr')->title;  // Titre Français

// Query by translated attribute
$germanPost = Post::transWhere('slug', 'mein-artikel', 'de')->first();

// Sort by translated attribute
$posts = Post::transOrderBy('title', 'asc', 'fr')->get();

// Check if translation exists
if ($post->hasTranslation('content', 'es')) {
    echo $post->getAttributeTranslated('content', 'es');
}

// No fallback
$spanishTitle = $post->noFallbackLocale()->getAttributeTranslated('title', 'es');
// Returns NULL if Spanish translation doesn't exist
```

--------------------------------

### Configure External Translation File

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Reference an external YAML file in theme.yaml to store translation strings.

```yaml
name: My Theme

translate: config/lang.yaml
```

```yaml
en:
    site.title: My Website
    menu.home: Home
fr:
    site.title: Mon Site
    menu.home: Accueil
```

--------------------------------

### Create Translatable Model Instance

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-cms-object.md

Instantiates the model class defined in $translatableModel or defaults to MLCmsObject.

```php
protected function createModel(): Model
```

--------------------------------

### Managing Translations Programmatically

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-page.md

Demonstrates how to set, save, retrieve, and check for translations on a model instance.

```php
// In backend form or API
$page = Page::find('home');

// Edit English (default)
$page->title = 'Home';
$page->save();

// Switch to French and translate
$page->lang('fr');
$page->title = 'Accueil';
$page->save();

// Retrieve in backend
$frenchTitle = $page->getAttributeTranslated('title', 'fr');

// Check if translation exists
if ($page->hasTranslation('title', 'de')) {
    // German translation exists
}

// On frontend, translation is automatic
// After fetch, $page->title contains the locale-specific value
// based on the current request locale
```

--------------------------------

### Console Commands

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/INDEX.md

Artisan commands provided by the plugin for managing message discovery and migrations.

```APIDOC
## Console Commands

### Description
CLI commands for managing translation messages and plugin data migrations.

### Commands
- **translate:scan**: Discover and import messages from the theme.
- **translate:scan --purge**: Clear and reimport all messages.
- **translate:migratev1**: Migrate from plugin v1 to v2.
```

--------------------------------

### Implement plural forms

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/guides-translation-workflow.md

Use pipe-separated strings to define different pluralization states.

```text
You have no items|You have 1 item|You have :count items
```

--------------------------------

### Execute Custom Scan

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Run the translate scan command after registering custom event listeners.

```bash
php artisan translate:scan
```

--------------------------------

### List all locales in PHP

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-locale.md

Returns a collection of locale objects, caching the result after the first call.

```php
$locales = Locale::listLocales();
foreach ($locales as $locale) {
    echo $locale->code;   // 'en', 'fr', 'de'
    echo $locale->name;   // 'English', 'Français', 'Deutsch'
    echo $locale->is_enabled;   // true/false
    echo $locale->is_default;   // true/false (only one)
}
```

--------------------------------

### Silent Theme Scanning Exception Handling

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/errors.md

Used in EventCoreRegistry::importMessagesFromTheme to prevent site-wide errors if theme scanning fails.

```php
try {
    (new ThemeScanner)->scanThemeConfigForMessages($themeCode);
} catch (Exception $ex) {
    // Silently ignore
}
```

--------------------------------

### Implement TranslatablePage Behavior

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Enable translation for CMS pages by implementing the TranslatablePage behavior.

```php
class MyPage extends Page
{
    public $implement = [
        'RainLab.Translate.Behaviors.TranslatablePage'
    ];

    public $translatable = [
        'title',
        'description',
        'meta_title'
    ];
}
```

--------------------------------

### Use Translatable Attachments

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/guides-translation-workflow.md

Set and retrieve different file attachments based on the active locale.

```php
$product = Product::find(1);

// Set English image
$product->image = $englishImage;

// Set French image
$product->lang('fr');
$product->image = $frenchImage;
$product->save();

// Retrieve
$englishImg = $product->lang('en')->image;
$frenchImg = $product->lang('fr')->image;
```

--------------------------------

### Verify Translation Configuration

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/guides-translation-workflow.md

Check if the translator is configured and retrieve the list of enabled locales.

```php
// Check if configured
$translator = Translator::instance();
if ($translator->isConfigured()) {
    echo 'Translation system ready';
}

// List configured locales
$locales = Locale::listEnabled();
// ['en' => 'English', 'fr' => 'Français']
```

--------------------------------

### Enable fallback locale

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Method signature for re-enabling fallback to the default locale.

```php
public function withFallbackLocale(): \October\Rain\Database\Model
```

--------------------------------

### Programmatic ThemeScanner usage

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Perform manual scans, import messages, purge missing entries, and extend scanning logic programmatically.

```php
use RainLab\Translate\Classes\ThemeScanner;

// Basic scan
$scanner = ThemeScanner::scan();
$discovered = $scanner->getFoundMessages();

// Import specific messages
$scanner->importMessages([
    'welcome.title' => 'Welcome to our site',
    'welcome.message' => 'Thanks for visiting'
], 'en', true);

// Get current messages and purge missing ones
$current = (new Message)->findMessages('en');
$scanner->purgeMissingMessages(array_keys($current));

// Scan specific theme
$scanner = new ThemeScanner;
$scanner->scanThemeConfigForMessages('my-theme-code');

// Extend scanner with custom logic
Event::listen('rainlab.translate.themeScanner.afterScan', function (ThemeScanner $scanner) {
    // Add custom discovered messages
    $custom = [
        'plugin.feature' => 'Feature from my plugin'
    ];
    $scanner->importMessages($custom, 'en', true);
});
```

--------------------------------

### Hook into Theme Scanner

Source: https://github.com/rainlab/translate-plugin/blob/master/README.md

Use this event listener to execute custom logic after the theme scanner completes its scan.

```php
Event::listen('rainlab.translate.themeScanner.afterScan', function (ThemeScanner $scanner) {
    // ...
});
```

--------------------------------

### ThemeScanner::scanForMessages()

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Discovers all translatable messages in the theme, including configuration, templates, components, and mail templates.

```APIDOC
## ThemeScanner::scanForMessages()

### Description
Orchestrates the scanning of theme configuration, templates, CMS components, and mail templates. Results are stored in the internal $foundMessages property.

### Signature
`public function scanForMessages(): void`
```

--------------------------------

### ThemeScanner::getFoundMessages()

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Returns all messages discovered by the scanner.

```APIDOC
## ThemeScanner::getFoundMessages()

### Description
Retrieves the array of discovered message keys and values.

### Signature
`public function getFoundMessages(): array`

### Returns
- **array** - Discovered message keys and values.
```

--------------------------------

### Locale::all

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-locale.md

Returns all locale definitions as an array.

```APIDOC
## public static function all(): array

### Description
Returns all locale definitions as a flattened array of Locale objects.

### Returns
- **array** - Array of Locale objects.
```

--------------------------------

### ThemeScanner::importMessages()

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Imports discovered messages into the database.

```APIDOC
## ThemeScanner::importMessages()

### Description
Updates internal message tracking and persists message codes to the database.

### Signature
`public function importMessages(array $messages, string|null $locale = null, bool $withKeys = false): void`

### Parameters
- **messages** (array) - Required - Message list or key-value pairs.
- **locale** (string|null) - Optional - Target locale; defaults to site default.
- **withKeys** (bool) - Optional - If true, array is key => value; if false, creates combined key and value.
```

--------------------------------

### Verify Translation Configuration and Existence

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/errors.md

Check if the translator is configured and ensure specific message keys exist in the database.

```php
// Verify configuration
if (!Translator::instance()->isConfigured()) {
    // Run migrations
    php artisan migrate
    // Import messages
    php artisan translate:scan
}

// Verify message exists
$exists = Message::getMessages('en');
if (!array_key_exists('my.key', $exists)) {
    Message::importMessageCodes(['my.key' => 'My Message'], 'en');
}
```

--------------------------------

### Use lang() Shorthand

Source: https://github.com/rainlab/translate-plugin/blob/master/README.md

The lang() method provides a chainable shorthand for translateContext().

```php
// Outputs the name in French
echo $user->lang('fr')->name;
```

```twig
{{ user.lang('fr').name }}
```

--------------------------------

### Access Translations via TranslatableModel

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-attribute-model.md

Standard usage pattern for retrieving translated content through the TranslatableModel behavior.

```php
$post = Post::find(1);
$post->lang('fr');  // Internally queries via Attribute relation
echo $post->title;  // French title from attributes table
```

--------------------------------

### Theme configuration translation formats

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Supported formats for defining translations within theme.yaml or external configuration files.

```yaml
translate:
    en:
        site.name: 'My Website'
        nav.home: 'Home'
    fr:
        site.name: 'Mon Site'
        nav.home: 'Accueil'
```

```yaml
translate: config/lang.yaml
```

```yaml
en:
    site.name: 'My Website'
fr:
    site.name: 'Mon Site'
```

```yaml
translate:
    en: config/lang-en.yaml
    fr: config/lang-fr.yaml
```

--------------------------------

### Implement cms.sitePicker.overridePattern logic

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-event-registry.md

Logic to check for translatable page URLs and return the translated attribute.

```php
if ($page->hasTranslatablePageUrl($proposedSite->hard_locale)) {
    return $page->getSettingsUrlAttributeTranslated($proposedSite->hard_locale);
}
```

--------------------------------

### Verify Messages

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Scans for messages to ensure data integrity after migration.

```bash
php artisan translate:scan  # Verify messages are intact
```

--------------------------------

### Handle theme scanner exceptions

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/errors.md

Ensures messages are scanned before purging and provides a try-catch block for handling scanner exceptions.

```php
if (!is_array($this->foundMessages)) {
    throw new Exception('Please run a scan first to avoid purging all messages.');
}
```

```php
try {
    $scanner->purgeMissingMessages($current);
} catch (Exception $ex) {
    // Scan not performed, handle error
}
```

--------------------------------

### Frontend Rendering and Template Processing

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-cms-object.md

Automatic locale detection and template processing for CMS objects.

```php
// Template processing
$page = Page::find('contact');
// Locale detection happens
// If French: loads contact-fr.htm
// If German: loads contact-de.htm
// Falls back to contact.htm if not found
```

--------------------------------

### Update Theme Messages

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

Workflow for importing new messages after modifying theme files.

```bash
# 1. Modify theme.yaml or add theme messages

# 2. Import new messages (merge with existing)
php artisan translate:scan

# 3. Edit translations in backend if needed

# 4. Clear cache
php artisan cache:clear
```

--------------------------------

### Translation Index Structure

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-attribute-model.md

Shows the difference between attribute data storage and indexed attribute storage.

```php
// rainlab_translate_attributes - stores all data
['attribute_data' => json_encode(['title' => 'Titre', 'slug' => 'titre'])]

// rainlab_translate_indexes - stores indexed attributes only
['item' => 'slug', 'value' => 'titre']  // For transWhere() queries
```

--------------------------------

### Index Attributes for Queries

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-model.md

Enable indexing for specific attributes to allow them to be used in transWhere() queries.

```php
public $translatable = [
    'title',
    ['slug', 'index' => true],
    ['status', 'index' => true]
];
```

--------------------------------

### Register Event Listeners

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Register custom logic for theme scanning and URL parameter transformation during locale switching in the plugin registration file.

```php
Event::listen('rainlab.translate.themeScanner.afterScan', function ($scanner) {
    // Custom scanning logic
});

Event::listen('cms.sitePicker.overrideParams', function ($page, $params, $oldSite, $newSite) {
    // Transform URL parameters when switching locales
    return $params;
});
```

--------------------------------

### Retrieve Translatable Attributes

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-page.md

Returns a list of translatable attributes formatted for settings storage.

```php
public function getTranslatableAttributes(): array
```

```php
// For $translatable = ['title', 'description']
// Returns: ['settings[title]', 'settings[description]']
```

--------------------------------

### loadLocaleFromSession()

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translator.md

Attempts to load and activate a locale from the session.

```APIDOC
## loadLocaleFromSession()

### Description
Attempts to load and activate a locale from the session.

### Returns
- **bool** - true if a valid locale was found and activated, false otherwise.
```

--------------------------------

### Configure Locale URLs in ViewBag

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-page.md

Define locale-specific paths for a page within the viewBag configuration block.

```yaml
url = "/contact"

[viewBag]
localeUrl[ru] = "/контакт"
localeUrl[fr] = "/contact"
```

--------------------------------

### Reference external translation files in theme.yaml

Source: https://github.com/rainlab/translate-plugin/blob/master/README.md

Point the translate key to a relative path for external YAML translation files.

```yaml
name: My Theme
# [...]

translate: config/lang.yaml
```

```yaml
name: My Theme
# [...]

translate:
    en: config/lang-en.yaml
    fr: config/lang-fr.yaml
```

--------------------------------

### Import message codes with Message::importMessageCodes

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-message.md

Creates or updates message records in bulk for a given locale.

```php
Message::importMessageCodes([
    'welcome' => 'Welcome to our site',
    'goodbye' => 'Goodbye!'
], 'en');
```

--------------------------------

### Expected Migration Output

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-console-commands.md

The success message displayed upon completion of the migration.

```text
Migration from v1 to v2 completed successfully.
```

--------------------------------

### Configure Inline Theme Translations

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Define translations directly within the theme.yaml file using a nested structure by locale.

```yaml
name: My Theme

translate:
    en:
        site.title: My Website
        site.slogan: The best site ever
        menu.home: Home
        menu.about: About Us
        menu.contact: Contact
    fr:
        site.title: Mon Site
        site.slogan: Le meilleur site jamais
        menu.home: Accueil
        menu.about: À Propos
        menu.contact: Contact
    de:
        site.title: Meine Website
        site.slogan: Die beste Website aller Zeiten
        menu.home: Startseite
        menu.about: Über Uns
        menu.contact: Kontakt
```

--------------------------------

### List available locales in PHP

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-locale.md

Returns enabled locales as a key-value array suitable for backend dropdowns.

```php
$options = Locale::listAvailable();
// Returns: ['en' => 'English', 'fr' => 'Français', 'de' => 'Deutsch']
```

--------------------------------

### Import messages into database

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-theme-scanner.md

Import message arrays into the database, supporting both simple value lists and explicit key-value pairs.

```php
$scanner = new ThemeScanner;

// Import from array of values (key and value are same)
$scanner->importMessages(['welcome', 'goodbye'], 'en');

// Import with explicit key-value pairs
$scanner->importMessages([
    'greeting.welcome' => 'Welcome',
    'greeting.goodbye' => 'Goodbye'
], 'en', true);
```

--------------------------------

### Implement TranslatableCmsObject Behavior

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/configuration.md

Apply translation support to CMS partials and layouts using the TranslatableCmsObject behavior.

```php
class MyContent extends Content
{
    public $implement = [
        'RainLab.Translate.Behaviors.TranslatableCmsObject'
    ];

    public $translatable = ['markup'];
    
    // Optional: specify custom model class
    public $translatableModel = 'MyPlugin\Classes\MLContent';
}
```

--------------------------------

### Theme Scanner Results Structure

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/types.md

Format returned by ThemeScanner::getFoundMessages().

```php
[
    'site.name' => 'My Website',
    'site.description' => 'Welcome',
    'nav.home' => 'Home',
    'nav.about' => 'About Us',
    'button.submit' => 'Submit'
]
```

--------------------------------

### Translate and Manage Messages

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-message.md

Demonstrates translating strings in PHP and Twig, importing message codes, updating translations, and querying messages with usage statistics.

```php
use RainLab	ranslate\Models\Message;

// Translate in code
$greeting = Message::trans('greetings.welcome'); // 'Welcome'
$hello = Message::trans('hello.name', ['name' => 'Alice']); // 'Hello Alice'

// Translate in Twig (via Plugin filters)
{{ 'welcome'|_ }}
{{ 'hello'|_({ name: 'Bob' }) }}

// Import messages programmatically
Message::importMessageCodes([
    'menu.home' => 'Home',
    'menu.about' => 'About Us',
    'menu.contact' => 'Contact'
], 'en');

// Update after import
(new Message)->updateMessages('fr', [
    'menu.home' => 'Accueil',
    'menu.about' => 'À Propos',
    'menu.contact' => 'Contact'
]);

// Find messages with usage stats
$messages = (new Message)->findMessages('en', [
    'withUsage' => true,
    'count' => 50
]);
// Returns: ['welcome' => '1 hour ago', 'goodbye' => 'Never', ...]

// Search messages
$results = (new Message)->findMessages('de', ['search' => 'button']);
```

--------------------------------

### CMS File Organization Structure

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-cms-object.md

Displays the expected directory structure for localized CMS files using language suffixes.

```text
pages/
  contact.htm          # Base/default (English)
  contact-fr.htm       # French
  contact-de.htm       # German
  contact-ru.htm       # Russian
```

--------------------------------

### Conditionally Implement TranslatableModel

Source: https://github.com/rainlab/translate-plugin/blob/master/README.md

Use the @ prefix to softly implement the TranslatableModel behavior, preventing errors if the Translate plugin is missing.

```php
/**
 * Post Model for the blog
 */
class Post extends Model
{
    // [...]

    /**
     * @var array implement the TranslatableModel behavior softly.
     */
    public $implement = ['@'.\RainLab\Translate\Behaviors\TranslatableModel::class];

    /**
     * @var array translatable attributes, if available.
     */
    public $translatable = ['title'];

    // [...]
}
```

--------------------------------

### Configure Translatable Model

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-behavior.md

Implement the TranslatableModel behavior and define translatable attributes within a model class.

```php
<?php namespace MyPlugin\Models;

use Model;

class Post extends Model
{
    public $implement = [
        'RainLab.Translate.Behaviors.TranslatableModel'
    ];

    public $translatable = [
        'title',
        'description',
        ['slug', 'index' => true] // Mark as indexed for transWhere() queries
    ];
}
```

--------------------------------

### Translate File Attachments

Source: https://github.com/rainlab/translate-plugin/blob/master/_autodocs/api-reference-translatable-model.md

Implement TranslatableModel to support localized file attachments, allowing each locale to have its own version of a file.

```php
class Product extends Model
{
    public $implement = ['RainLab.Translate.Behaviors.TranslatableModel'];
    
    public $translatable = ['name', 'image'];  // 'image' is attachOne
    public $attachOne = ['image' => 'System\Models\File'];
}

// Each locale gets its own file version
$product->lang('fr')->image; // French image
$product->lang('de')->image; // German image
```
Tokens:
Raw