locale_dirs default value inconsistency

[rffontenelle]

Describe the bug

sphinx-build searches for translation files in the directory 'locale', even though
locale_dirs conf value defaults to 'locales' since Sphinx 1.5, as per changelog entry.

This causes weird behaviors like sphinx-intl looking for translations in 'locales' (sphinx-doc/sphinx-intl#14), but sphinx-build builds translated docs using translations from 'locale'.

Related code (I think, not sure though):

sphinx/sphinx/application.py

Line 321 in a1510de

locale_dirs += [path.join(package_dir, 'locale')]

sphinx/sphinx/config.py

Line 217 in a1510de

'locale_dirs': _Opt(['locales'], 'env', ()),

How to Reproduce

# Get sphinx and sphinx-doc-translations sources
git clone --single-branch --depth 1 --branch 3.13 https://github.com/python/cpython
git clone --single-branch --depth 1 --branch 3.13 https://github.com/python/python-docs-pt-br cpython/Doc/locale/pt_BR/LC_MESSAGES
# Enter sphinx dir
cd cpython/Doc
# Build translated from locale
make html SPHINXOPTS='-Dlanguage=pt_BR'
# and check built files, should be translated
# Now rename directory
mv locale locales
# Again build translated from locale
make html SPHINXOPTS='-Dlanguage=pt_BR'
# and check the built files, which should NOT be translated now.

Environment Information

Latest sphinx commit

Sphinx extensions

No response

Additional context

No response

[AA-Turner]

locale_dirs += [path.join(package_dir, 'locale')] is using the Sphinx sphinx.locale directory as a final fallback, so I think unrelated.

[rffontenelle]

@AA-Turner I see. So the usage/configuration page that says locale_dirs defaults to 'locales' is incorrect, right?

[AA-Turner]

config.locale_dirs defaults to ['locales']

When I try and run locally with the .mo files under Doc/locales/pt_BR/LC_MESSAGES, I get translated results. When under Doc/locale, I don't.

This seems opposite to your reproducer @rffontenelle?

A

[rffontenelle]

It doesn't, hence my original statement is incorrect (now?). Proposed a fix for the Configuration page that is currently stating 'locale' is the default.