[gettext] Deprecate l*gettext() functions and related (#14535)

Author: donBarbos

stdlib/gettext.pyi

@@ -3,6 +3,7 @@ import sys
 from _typeshed import StrPath
 from collections.abc import Callable, Container, Iterable, Sequence
 from typing import Any, Final, Literal, Protocol, TypeVar, overload, type_check_only
+from typing_extensions import deprecated
 
 __all__ = [
     "NullTranslations",
@@ -145,9 +146,16 @@ else:
         fallback: bool = False,
         codeset: str | None = None,
     ) -> NullTranslations: ...
+    @overload
     def install(
-        domain: str, localedir: StrPath | None = None, codeset: str | None = None, names: Container[str] | None = None
+        domain: str, localedir: StrPath | None = None, codeset: None = None, names: Container[str] | None = None
     ) -> None: ...
+    @overload
+    @deprecated("The `codeset` parameter is deprecated since Python 3.8; removed in Python 3.11.")
+    def install(domain: str, localedir: StrPath | None, codeset: str, /, names: Container[str] | None = None) -> None: ...
+    @overload
+    @deprecated("The `codeset` parameter is deprecated since Python 3.8; removed in Python 3.11.")
+    def install(domain: str, localedir: StrPath | None = None, *, codeset: str, names: Container[str] | None = None) -> None: ...
 
 def textdomain(domain: str | None = None) -> str: ...
 def bindtextdomain(domain: str, localedir: StrPath | None = None) -> str: ...
@@ -161,10 +169,15 @@ def npgettext(context: str, msgid1: str, msgid2: str, n: int) -> str: ...
 def dnpgettext(domain: str, context: str, msgid1: str, msgid2: str, n: int) -> str: ...
 
 if sys.version_info < (3, 11):
+    @deprecated("Deprecated since Python 3.8; removed in Python 3.11. Use `gettext()` instead.")
     def lgettext(message: str) -> str: ...
+    @deprecated("Deprecated since Python 3.8; removed in Python 3.11. Use `dgettext()` instead.")
     def ldgettext(domain: str, message: str) -> str: ...
+    @deprecated("Deprecated since Python 3.8; removed in Python 3.11. Use `ngettext()` instead.")
     def lngettext(msgid1: str, msgid2: str, n: int) -> str: ...
+    @deprecated("Deprecated since Python 3.8; removed in Python 3.11. Use `dngettext()` instead.")
     def ldngettext(domain: str, msgid1: str, msgid2: str, n: int) -> str: ...
+    @deprecated("Deprecated since Python 3.8; removed in Python 3.11. Use `bindtextdomain()` instead.")
     def bind_textdomain_codeset(domain: str, codeset: str | None = None) -> str: ...
 
 Catalog = translation