locale_gen: fix/improvements (#9238)

* locale_gen: fix/improvements

* fix sanity

* add RV doc

* add integration test forcing mechanism=debian

- test is failing

* fix RETURN doc

* reformat yaml

* comment out the test for ubuntu_mode=True

* multiple changes:

- add changelog fragment
- improved docs

* normalize docs after rebasing

* Update changelogs/fragments/9131-locale-gen-rewrite.yml

* apply recommendations from review

* Update plugins/modules/locale_gen.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update changelogs/fragments/9238-locale-gen-rewrite.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/modules/locale_gen.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/modules/locale_gen.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/9238-locale-gen-rewrite.yml

@@ -0,0 +1,13 @@
+minor_changes:
+  - "locale_gen - invert the logic to determine ``ubuntu_mode``, making it look first for ``/etc/locale.gen`` (set ``ubuntu_mode`` to ``False``)
+    and only then looking for ``/var/lib/locales/supported.d/`` (set ``ubuntu_mode`` to ``True``)
+    (https://github.com/ansible-collections/community.general/pull/9238,
+    https://github.com/ansible-collections/community.general/issues/9131,
+    https://github.com/ansible-collections/community.general/issues/8487)."
+  - >
+    locale_gen - new return value ``mechanism`` to better express the semantics of the ``ubuntu_mode``, with the possible values being either
+    ``glibc`` (``ubuntu_mode=False``) or ``ubuntu_legacy`` (``ubuntu_mode=True``) (https://github.com/ansible-collections/community.general/pull/9238).
+deprecated_features:
+  - >
+    locale_gen - ``ubuntu_mode=True``, or ``mechanism=ubuntu_legacy`` is deprecated and will be removed in community.general 13.0.0
+    (https://github.com/ansible-collections/community.general/pull/9238).