You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "pbaumard (via GitHub)" <gi...@apache.org> on 2026/01/28 11:27:33 UTC
[I] Default locale should be the first valid token from _locales_ [maven-site-plugin]
pbaumard opened a new issue, #1226:
URL: https://github.com/apache/maven-site-plugin/issues/1226
### 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](https://maven.apache.org/plugins/maven-site-plugin/site-mojo.html),
`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:
```xml
<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/
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Default locale should be the first valid token from locales [maven-site-plugin]
Posted by "michael-o (via GitHub)" <gi...@apache.org>.
michael-o commented on issue #1226:
URL: https://github.com/apache/maven-site-plugin/issues/1226#issuecomment-3885682779
> > 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>`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Default locale should be the first valid token from locales [maven-site-plugin]
Posted by "pbaumard (via GitHub)" <gi...@apache.org>.
pbaumard commented on issue #1226:
URL: https://github.com/apache/maven-site-plugin/issues/1226#issuecomment-3884252980
> 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?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Default locale should be the first valid token from locales [maven-site-plugin]
Posted by "kwin (via GitHub)" <gi...@apache.org>.
kwin commented on issue #1226:
URL: https://github.com/apache/maven-site-plugin/issues/1226#issuecomment-3878282451
@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?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Default locale should be the first valid token from locales [maven-site-plugin]
Posted by "michael-o (via GitHub)" <gi...@apache.org>.
michael-o commented on issue #1226:
URL: https://github.com/apache/maven-site-plugin/issues/1226#issuecomment-3878708943
> [@michael-o](https://github.com/michael-o) Since you introduced the change deliberately in [#1083](https://github.com/apache/maven-site-plugin/issues/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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Default locale should be the first valid token from locales [maven-site-plugin]
Posted by "pbaumard (via GitHub)" <gi...@apache.org>.
pbaumard commented on issue #1226:
URL: https://github.com/apache/maven-site-plugin/issues/1226#issuecomment-3889135061
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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Default locale should be the first valid token from locales [maven-site-plugin]
Posted by "michael-o (via GitHub)" <gi...@apache.org>.
michael-o commented on issue #1226:
URL: https://github.com/apache/maven-site-plugin/issues/1226#issuecomment-3940568830
> > We have several ITs covering your exact case. It boils down to: default,de,fr_CA,ar_SA,pl
>
> [@michael-o](https://github.com/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](https://github.com/apache/maven-site-plugin/issues/1083), it would make it easier to propose a solution that supports both scenarios.
>
> > [@michael-o](https://github.com/michael-o) Since you introduced the change deliberately in [#1083](https://github.com/apache/maven-site-plugin/issues/1083) what is your opinion? Do we need to change documentation or implementation in this regard?
>
> [@kwin](https://github.com/kwin) I’d also like to highlight that [#1083](https://github.com/apache/maven-site-plugin/issues/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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Default locale should be the first valid token from locales [maven-site-plugin]
Posted by "pbaumard (via GitHub)" <gi...@apache.org>.
pbaumard commented on issue #1226:
URL: https://github.com/apache/maven-site-plugin/issues/1226#issuecomment-3945244274
> 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org