Default locale should be the first valid token from locales

[pbaumard]

Affected version

3.20.0

Bug description

Description

Since the changes introduced in issue #1083, the default locale used by site:site is no longer the first valid token in the locales parameter.
This breaks the documented behavior and alters long‑established expectations.

According to the plugin’s site:site documentation,
locales is “a comma separated list of locales to render. The first valid token will be the default Locale for this site.”.

The behavior before #1083 followed this rule.
The changes introduced there should be reverted.

Steps to Reproduce

Configure the plugin with:

<locales>fr</locales>

Expected Behavior

With locales = fr, the default locale should be fr, and the default output directory should remain:
target/site/

Actual Behavior

The generated site is placed under a locale‑specific directory:
target/site/fr/

[kwin]

@michael-o Since you introduced the change deliberately in #1083 what is your opinion? Do we need to change documentation or implementation in this regard?

[michael-o]

@michael-o Since you introduced the change deliberately in #1083 what is your opinion? Do we need to change documentation or implementation in this regard?

Change docs saying that if no locales are provided the default is assumed. If locales are provided they are explicit and if default is needed it needs to be provided as well. We have ITs depiciting the behavior as far as I remember.

[pbaumard]

If locales are provided they are explicit and if default is needed it needs to be provided as well.

I’m having trouble understanding the statement.

The term “default” seems ambiguous here, and I’m unsure which of the following meanings is intended:

1. A literal "default" token inside the <locales> parameter, which would then map to the system default locale.
2. The system default locale itself, which is generally difficult to change and may not be what the user wants.
3. The default site output directory (target/site/), which previously was produced using the first valid locale listed in <locales>.

Given this ambiguity, could you clarify which interpretation is correct?

Also, if the current implementation is not meant to change, how would the use case described in this issue be achieved in practice?

[michael-o]

If locales are provided they are explicit and if default is needed it needs to be provided as well.

I’m having trouble understanding the statement.

OK, let's go through:

The term “default” seems ambiguous here, and I’m unsure which of the following meanings is intended:

1. A literal "default" token inside the `<locales>` parameter, which would then map to the system default locale.

No, "default" means for Maven Doxia Sitetools, not the JVM. Relying on the JVM locale is horribly brittle. System (JVM) default is "system". This is also document. "default" locale is always Locale#ROOT.

2. The system default locale itself, which is generally difficult to change and may not be what the user wants.

Correct, see above.

3. The default site output directory (target/site/), which previously was produced using the first valid locale listed in  `<locales>`.

Documentation needs to change.

Also, if the current implementation is not meant to change, how would the use case described in this issue be achieved in practice?

We have several ITs covering your exact case. It boils down to: <locales>default,de,fr_CA,ar_SA,pl</locale>

[pbaumard]

We have several ITs covering your exact case. It boils down to: default,de,fr_CA,ar_SA,pl

@michael-o As far as I understand, none of the current <locales> configurations seem to cover the use case described in this ticket, where a French site is expected to be generated in the src/site root directory on an English system.

• <locales>default</locales> would generate the site in English.
• <locales>fr</locales> would generate the French site under src/site/fr, not directly in src/site.

If I understood the use case that motivated the breaking change in #1083, it would make it easier to propose a solution that supports both scenarios.

@michael-o Since you introduced the change deliberately in #1083 what is your opinion? Do we need to change documentation or implementation in this regard?

@kwin I’d also like to highlight that #1083 introduced a breaking change that affects existing users without providing any alternative or migration path. Because of that, simply updating the documentation doesn’t seem like a viable long‑term solution. It would be preferable to restore backward compatibility or provide a configurable option so users are not forced into the new behavior.

[michael-o]

We have several ITs covering your exact case. It boils down to: default,de,fr_CA,ar_SA,pl

@michael-o As far as I understand, none of the current <locales> configurations seem to cover the use case described in this ticket, where a French site is expected to be generated in the src/site root directory on an English system.

* `<locales>default</locales>` would generate the site in English.

* `<locales>fr</locales>` would generate the French site under src/site/fr, not directly in src/site.

If I understood the use case that motivated the breaking change in #1083, it would make it easier to propose a solution that supports both scenarios.

@michael-o Since you introduced the change deliberately in #1083 what is your opinion? Do we need to change documentation or implementation in this regard?

@kwin I’d also like to highlight that #1083 introduced a breaking change that affects existing users without providing any alternative or migration path. Because of that, simply updating the documentation doesn’t seem like a viable long‑term solution. It would be preferable to restore backward compatibility or provide a configurable option so users are not forced into the new behavior.

I see, can you please a sample test case for me, I'd like to have a look at it? Our premise was that our root bundles are fixed and contain English content (default) and any other specific locale can overwrite even en_CA/en_US like catalogue/catalog.

[pbaumard]

I see, can you please a sample test case for me

I added an Integration Test in #1234 and a tentative fix which takes the first token in locales as the site root if no "default" is included in locales.