How to Set Up Domains and Locales (Languages)¶

This article describes how to work with domains and languages during the development of your project. For an explanation of the basic terms, please read domain, multidomain and multilanguage article first.

Settings and working with domains¶

1. How to create a single domain application¶

1.1 Domain configuration¶

Modify the configuration of the domain in config/domains.yaml. This configuration file contains information about the domain ID, the domain identifier for the domain tabs in the administration, and the domain locale.

1.2 Set up the url address¶

Set the url address for the domain in config/domains_urls.yaml.

1.3 Locale settings¶

Set up the locale of the domain according to the instructions in the section Locale settings

1.4 Build¶

Start the build, for example, using a phing target

php phing build-demo-dev

After the build is completed, a singledomain application is created.

1.5 Tests¶

Some tests are prepared for the specific configuration and test only the behavior for the default locales (en and/or cs). For example Tests\App\Functional\Twig\PriceExtensionTest is expecting the specific format of displayed currency. If you want to use already created tests for your specific configuration, you may need to modify these tests to be able to test your specific configuration of the domain.

2. How to add a new domain¶

2.1 Domain configuration¶

Modify the configuration of the domain in config/domains.yaml. This configuration file contains pieces of information about the domain ID, the domain identifier for the domain tabs in the administration, and the domain locale.

2.2 Set up the url address¶

Set the url address for the domain in config/domains_urls.yaml.

Domain URLs with Postfixes¶

Configuration Structure:

• url: Full domain URL including postfix (e.g., http://127.0.0.1:8000/sk)
• baseUrl: Automatically extracted base URL (e.g., http://127.0.0.1:8000)
• postfix: Automatically extracted path segment (e.g., /sk)

Example configuration in config/domains_urls.yaml:

domains_urls:
    - id: 1
      url: http://127.0.0.1:8000
    - id: 2
      url: http://127.0.0.1:8000/cs
    - id: 3
      url: http://127.0.0.1:8000/sk

2.3 Locale settings¶

Set up the locale of the domain according to the instructions in the section Locale settings

2.4 Create multidomains data¶

There need to be created some multidomain data for the newly added domain. Run the phing target

php phing domains-data-create

This command performs multiple actions:

• multidomain attributes from the first domain are copied for this new domain, see FrameworkBundle/Component/Domain/DomainDataCreator.php, where the TEMPLATE_DOMAIN_ID constant is defined.
• if a new locale is set for the newly added domain, the empty rows with this new locale will be created for multilang attributes
• pricing group with the name Default is created for every new domain
• the last step of this command is the start of automatic recalculations of prices, availabilities, and products visibilities.

2.5 Multilang attributes¶

Demo data of Shopsys Platform are translated only for en and cs locales. If you have set a different locale, you can use translations-dump that will create new translation files in translations directory and you can translate your demo data in dataFixtures.xx.po file.

2.6 Generate assets for the new domain¶

In order to properly display the new domain, assets need to be generated

php phing npm

2.7. Create elasticsearch definition for the new domain¶

The configuration for elasticsearch must be created for each domain in a separate json file. By default, the configurations for the domain 1 and 2 are already parts of a project-base. Configuration for elasticsearch can be found in src/Resources/definition/. If you add a new domain, you need to create an elasticsearch configuration for this new domain.

After you create the configuration, you have to create the index in elasticsearch and fill it by data

php phing elasticsearch-index-recreate
php phing elasticsearch-export

3. Locale settings¶

Some parts of these instructions are already prepared for the locales en and cs.

3.1 Set up the locale for domain¶

Set up the locale of the domain in config/domains.yaml. This configuration file contains pieces of information about the domain ID, the domain identifier for the domain tabs in the administration, and the domain locale.

3.2 Frontend routes¶

Create a file with the frontend routes for the added locale if this file is not already created for this locale. Create this file in the directory config/shopsys-routing with the name routing_front_xx.yaml where xx replace for the code of added locale.

3.3 Translations and messages¶

In order to correctly display the labels like Registration, Cart, ..., create a file with translations of messages in translations directory.

Then run

php phing translations-dump

There will be created files for translations of messages for the new locale in translations directory, which you'll need to translate:

• messages.xx.po for translations of common strings
• validators.xx.po for translations of validation messages
• dataFixtures.xx.po for translations of demo data

For more information about translations, see the separate article.

3.4 Generate database functions for the locale use¶

Within the database functions, it is necessary to regenerate the default database functions for the locale use that are already created for the en locale as default. Regenerate database functions by running a phing target

php phing domains-db-functions-create

3.5 Multilang attributes¶

Demo data of Shopsys Platform are prepared only for en and cs locales. If you have set a different locale, you can use translations-dump that will create new translation files in translations directory and you can translate your demo data in dataFixtures.xx.po file.

3.6 Administration Domain Access Restrictions¶

Behavior with Domain Postfixes:

• Admin is always accessible from the base URL of the first domain (without postfix)
• Even if the first domain has a postfix (e.g., http://127.0.0.1:8000/en), admin access is at http://127.0.0.1:8000/admin (base URL)
• Access attempts from other domains are redirected to the first domain's base URL

Admin URL Configuration:

• Admin path is configurable via ADMIN_URL environment variable (default: admin)
  • This environment variable has to be set separately for php_fpm and webserver containers
  • If you use shopsys/deployment package to deploy your application, you just need to set the environment variable in GitLab and after deploy, the change is automatically propagated to both containers
• All admin URLs use this path: http://first-domain/{admin_url}/...
• Example: If %admin_url% is set to administration, admin is at http://127.0.0.1:8000/administration
• This setting affects both redirect behavior and admin route generation

Admin Routes Configuration:

• AdministrationRouter handles URL generation within admin context
• Admin routes are defined in config/routes-administration/shopsys_admin.yaml
• All admin routes use prefix: /%admin_url% to respect the configurable admin path
• Routes include framework controllers, project controllers, and administration routes from other packages (e.g., frontend-api)

3.7 Locale in administration¶

Administration uses the en locale by default for every newly created administrator. This means that all the static texts are in English. Furthermore, all data translations (e.g. the product names in the administration list) are presented in the en locale. When the administrator uses a locale that is not used on any domain, there are no persisted translations for this locale so in this case, the data are displayed in the first domain locale. You can adjust this behavior by setting the desired $fallbackLocaleDomainId in Localization::getCurrentLocaleForTranslatableEntities() method call in particular scenarios.

The administrator can then change the locale to fit his needs to any of the locales defined by the shopsys.allowed_admin_locales parameter in your config/parameters_common.yaml. If you want to switch the default value to another locale or restrict the locales an administrator can choose from, set the shopsys.allowed_admin_locales parameter in your config/parameters_common.yaml configuration accordingly. The first locale in the list is the default one.

You can change administration translations by adding messages into your translations/messages.xx.po.

3.8 Sorting in different locales¶

Alphabetical sorting on frontend uses Elasticsearch and its ICU analysis plugin.
Every domain needs to have language parameter for field name.keyword in src/Resources/definition/product/*.json set in order to sort correctly for given locale.

An example for domain that uses English language:

"name": {
    "type": "text",
    "analyzer": "stemming",
    "fields": {
        "keyword": {
            "type": "icu_collation_keyword",
            "language": "en",
            "index": false
        }
    }
}

3.9 Default application locale¶

In most cases, when working with multilanguage attributes, you do not need to specify any locale as it is set automatically from the request so you can just use e.g., Product::getName() and you get the proper translation. However, sometimes, there is no request (i.e. in CLI commands) so you need to tell your application, which locale should be used - either using a parameter in the method (Product::getName('es')) or by setting a default application locale.

To change the default application locale, set locale parameter to your desired locale (e.g., es for Spanish) in your parameters_common.yaml. The value is then used for setting default_locale Symfony parameter (see your config/packages/translation.yaml config).

4. Change the url address for an existing domain¶

4.1 Change the url address¶

Change the url address in the configuration of the domain in config/domains_urls.yaml.

4.2 Replace the old url address¶

Run the phing target

php phing domains-urls-replace

Running this command will ensure replacing all occurrences of the old url address in the text attributes in the database with the new url address.

5. Change the locale for an existing domain¶

This scenario is not supported by default because of the fact, that change of the locale within an already running eshop almost never happens. However, there is workaround even for this scenario.

5.1 Change the locale to the locale that is already used by another domain¶

If you need to change the locale of a specific domain to another locale that is already used by another domain, just set the required locale for this domain in the config/domains.yaml.

5.2 Change the locale to the locale that is not yet used by another domain¶

If you need to change the locale of a specific domain to another locale that is not yet already used by another domain, add new temporary domain with this new locale and follow the instructions of How to add a new domain. The following procedure is the same as in the case with Change the locale to the locale that is already used by another domain.