Cloud 7.02

Change Locale on Cloud

Understanding locale locking, enabling SCD_ON_DEMAND, config:dump workflow, and deploying locale changes.

Exam Critical: Understanding how to change locales on Cloud and the locale locking mechanism is important for the exam!

Changing Locales on Cloud

mindmap root((Change Locale)) The Challenge Production mode Locks locales Only pre generated Solution Enable SCD_ON_DEMAND Integration environment Unlock locale editing Steps 1 Add variable 2 Store redeploys 3 Change locale 4 config dump 5 Git commit Key Command vendor bin ece tools config dump Updates config php Commit to repo

The Challenge: Locale Locking in Production Mode

Why Magento Locks Locales

Production Mode Behavior

Magento locks the locales to ones that have their static content generated when in production mode.

Why This Happens:
  • Performance: Only pre-generated locales have static content ready
  • Consistency: Prevents users from selecting locales without static content
  • Errors prevention: Avoids broken storefront from missing static files
The Problem:

If you want to add a new locale (e.g., French, German, Spanish), you cannot simply change it in Stores → Configuration → General → Locale Options because the field is locked to pre-generated locales only.

Locked vs Unlocked Locales

Locked (Default Production)
  • Locale dropdown limited to pre-generated locales
  • Cannot add new locales without SCD
  • Admin field is restricted
  • Secure but inflexible
Unlocked (SCD_ON_DEMAND)
  • Locale dropdown shows ALL available locales
  • Can add new locales on demand
  • Admin field is editable
  • Flexible but slower first load

The Solution: Enable SCD_ON_DEMAND

Key to Unlocking Locale Editing

Why SCD_ON_DEMAND?

If you wish to change locales, the key is to enable SCD_ON_DEMAND in the integration environment.

What SCD_ON_DEMAND Does:
  • Applies the unlock_locale_editing patch
  • Unlocks locale selection in admin panel
  • Allows any locale to be selected (not just pre-generated)
  • Generates static content on demand for new locale
  • Enables locale changes without full SCD rebuild

Best Practice

Enable SCD_ON_DEMAND in integration environment to test and configure locales, then dump configuration to config.php for other environments.

Step-by-Step: How to Change a Locale on Cloud

Complete Workflow

Step 1: Enable SCD_ON_DEMAND in Integration

Project Web Interface
  1. Log in to Project Web Interface
  2. Select your Integration environment
  3. Navigate to Settings → Variables
  4. Click Add Variable
  5. Set:
    • Name: env:SCD_ON_DEMAND
    • Value: true
  6. Save the variable

Auto-Redeploy

Adding the variable will automatically redeploy the store. Wait for deployment to complete before proceeding.

Step 2: Change the Locale in Admin

  1. Access admin panel of integration environment
  2. Navigate to Stores → Configuration → General → Locale Options
  3. Notice locale dropdown is now unlocked (all locales available)
  4. Select desired locale (e.g., fr_FR for French France)
  5. Select appropriate scope:
    • Store View level for specific store
    • Website level for entire website
    • Default Config for all stores
  6. Click Save Config
  7. Clear cache: bin/magento cache:flush

Step 3: Dump Configuration

Run config:dump Command

SSH into integration environment and run:

./vendor/bin/ece-tools config:dump
What This Does:
  • Exports locale configuration from database to app/etc/config.php
  • Includes store configuration (websites, stores, store views)
  • Includes system configuration (locales, themes, etc.)
  • Locks configuration across environments

Step 4: Verify config.php Changes

git diff app/etc/config.php
Expected Changes

You should see locale configuration added/updated in config.php:

'system' => [
    'default' => [
        'general' => [
            'locale' => [
                'code' => 'fr_FR'
            ]
        ]
    ]
]

Step 5: Commit and Push to Git

git add app/etc/config.php
git commit -m "Add French locale configuration"
git push origin integration

Deployment Flow

Once pushed, the configuration will be deployed to all environments. Other environments (staging, production) will now have the locale configuration from config.php.

What Happens in Other Environments?

Staging and Production

Configuration Inheritance

When you merge to staging/production:

  1. config.php is deployed: Contains locale configuration
  2. SCD runs (build phase): Generates static content for new locale
  3. Locale is available: But field is locked in admin (from config.php)
  4. Static content exists: All files for new locale are pre-generated

Result

The new locale works in staging/production with pre-generated static content (no SCD_ON_DEMAND needed), and configuration is locked for consistency.

Alternative: Using .magento.env.yaml

Configuration File Method

Instead of using Project Web Interface, you can add to .magento.env.yaml:

stage:
  deploy:
    SCD_ON_DEMAND: true

Scope Difference

  • Project Web Interface: Per-environment (integration only)
  • .magento.env.yaml: All environments (unless overridden)
  • Best practice: Use Project Web Interface for integration only

Complete Example Workflow

Adding Spanish Locale

Scenario

You need to add Spanish (Spain) - es_ES locale to your store.

Step-by-Step Process

Step Action Location Command/Path
1 Enable SCD_ON_DEMAND Project Web Interface Settings → Variables → Add env:SCD_ON_DEMAND = true
2 Wait for redeploy Integration environment Monitor deployment logs
3 Change locale Admin panel Stores → Configuration → General → Locale Options → Select es_ES
4 Save configuration Admin panel Click "Save Config"
5 Dump configuration SSH (integration) ./vendor/bin/ece-tools config:dump
6 Review changes SSH (integration) git diff app/etc/config.php
7 Commit to git SSH (integration) git add app/etc/config.php
git commit -m "Add Spanish locale"
8 Push to repository SSH (integration) git push origin integration
9 Merge to staging Project Web Interface or CLI Merge integration → staging
10 SCD runs in build Staging deployment Automatic (generates es_ES static content)

Important Considerations

Best Practices and Warnings

Best Practices

  • Use integration: Always test locale changes in integration first
  • Dump configuration: Always run config:dump to persist changes
  • Commit config.php: Essential for deploying to other environments
  • Test thoroughly: Verify static content generation in staging
  • Document locales: Keep track of which locales are configured

Common Pitfalls

  • Forgetting config:dump: Changes only in database, not in config.php (lost on redeploy)
  • Not committing config.php: Changes won't deploy to other environments
  • Enabling SCD_ON_DEMAND in production: Causes slow page loads (development only!)
  • Not testing SCD: May fail in staging/production if locale not supported

Critical: Remove SCD_ON_DEMAND After Configuration

After dumping configuration and committing to git, remove or disable SCD_ON_DEMAND from integration. It should only be enabled temporarily for locale configuration!

Troubleshooting

Common Issues and Solutions

Issue 1: Locale Still Locked After Enabling SCD_ON_DEMAND

Solution:
  • Verify variable name is exactly env:SCD_ON_DEMAND
  • Wait for full deployment to complete
  • Clear browser cache and refresh admin panel
  • Check deployment logs for errors

Issue 2: config:dump Doesn't Include Locale Changes

Solution:
  • Ensure you saved configuration in admin panel
  • Clear Magento cache before running config:dump
  • Verify changes are in database: SELECT * FROM core_config_data WHERE path LIKE '%locale%'

Issue 3: Static Content Missing for New Locale in Staging

Solution:
  • Verify locale code is valid and supported by Magento
  • Check build logs for SCD errors
  • Ensure locale is properly configured in config.php
  • Manually trigger SCD if needed: bin/magento setup:static-content:deploy es_ES

Related Commands

Useful Commands for Locale Management

Command Purpose
./vendor/bin/ece-tools config:dump Dump configuration to config.php
bin/magento info:language:list List all available locales
bin/magento setup:static-content:deploy es_ES Generate static content for specific locale
bin/magento cache:flush Clear cache after locale changes
git diff app/etc/config.php Review configuration changes

Exam Tips

Key Points to Remember

  • Challenge: Production mode locks locales to pre-generated ones
  • Solution: Enable SCD_ON_DEMAND in integration environment
  • Location: Project Web Interface → Settings → Variables
  • Variable name: env:SCD_ON_DEMAND = true
  • Auto-redeploy: Adding variable triggers automatic redeployment
  • Admin unlock: Locale dropdown becomes editable with all locales
  • Critical command: ./vendor/bin/ece-tools config:dump
  • What it does: Exports configuration from database to app/etc/config.php
  • Must commit: app/etc/config.php to git repository
  • Other environments: Use config.php with pre-generated SCD (no SCD_ON_DEMAND)
  • Best practice: Remove SCD_ON_DEMAND after configuration
  • unlock_locale_editing patch: Applied by SCD_ON_DEMAND to unlock locale selection
  • Integration only: Enable SCD_ON_DEMAND in integration, not staging/production
Previous: Cloud 7.01 Change Configurations Practice Cloud 7.02