Bug 36947: (QA follow-up) Add missing POD documentation to Koha::I18N

The Koha::I18N module was missing POD documentation. This adds complete
documentation for all exported functions including usage examples and
descriptions.

Signed-off-by: David Cook <dcook@prosentient.com.au>
Signed-off-by: Martin Renvoize <martin.renvoize@openfifth.co.uk>
Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
(cherry picked from commit 5acbf16948)
Signed-off-by: Paul Derscheid <paul.derscheid@lmscloud.de>

Koha/I18N.pm

@@ -59,6 +59,45 @@ our @EXPORT_OK = qw(
 
 our $textdomain = 'Koha';
 
+=head1 NAME
+
+Koha::I18N - Internationalization functions for Koha
+
+=head1 SYNOPSIS
+
+    use Koha::I18N;
+
+    # Basic translation functions
+    my $translated = __('Hello world');
+    my $with_vars = __x('Hello {name}', name => 'World');
+    my $plural = __n('one item', '{count} items', $count, count => $count);
+
+    # Context-aware translations
+    my $context = __p('menu', 'File');
+
+    # Get available system locales (explicitly imported)
+    use Koha::I18N qw(available_locales);
+    my $locales = available_locales();
+
+=head1 DESCRIPTION
+
+This module provides internationalization (i18n) functions for Koha using the
+GNU gettext system. It handles locale setup, message translation, and provides
+utility functions for working with system locales.
+
+The module automatically initializes the locale environment and provides a set
+of translation functions that support variable substitution, plural forms, and
+contextual translations.
+
+=head1 FUNCTIONS
+
+=head2 init
+
+Initializes the internationalization system by setting up locale environment
+variables and configuring gettext. This is called automatically when needed.
+
+=cut
+
 sub init {
     my $cache     = Koha::Cache::Memory::Lite->get_instance();
     my $cache_key = 'i18n:initialized';
@@ -96,6 +135,14 @@ sub init {
     }
 }
 
+=head2 __
+
+    my $translated = __('Text to translate');
+
+Basic translation function. Returns the translated text for the given message ID.
+
+=cut
+
 sub __ {
     my ($msgid) = @_;
 
@@ -104,6 +151,15 @@ sub __ {
     return _gettext( \&gettext, [$msgid] );
 }
 
+=head2 __x
+
+    my $translated = __x('Hello {name}', name => 'World');
+
+Translation with variable substitution. Variables in {brackets} are replaced
+with the corresponding values from the provided hash.
+
+=cut
+
 sub __x {
     my ( $msgid, %vars ) = @_;
 
@@ -112,6 +168,14 @@ sub __x {
     return _gettext( \&gettext, [$msgid], %vars );
 }
 
+=head2 __n
+
+    my $translated = __n('one item', '{count} items', $count);
+
+Plural-aware translation. Returns singular or plural form based on the count.
+
+=cut
+
 sub __n {
     my ( $msgid, $msgid_plural, $count ) = @_;
 
@@ -121,6 +185,14 @@ sub __n {
     return _gettext( \&ngettext, [ $msgid, $msgid_plural, $count ] );
 }
 
+=head2 __nx
+
+    my $translated = __nx('one item', '{count} items', $count, count => $count);
+
+Plural-aware translation with variable substitution.
+
+=cut
+
 sub __nx {
     my ( $msgid, $msgid_plural, $count, %vars ) = @_;
 
@@ -130,10 +202,25 @@ sub __nx {
     return _gettext( \&ngettext, [ $msgid, $msgid_plural, $count ], %vars );
 }
 
+=head2 __xn
+
+Alias for __nx.
+
+=cut
+
 sub __xn {
     return __nx(@_);
 }
 
+=head2 __p
+
+    my $translated = __p('context', 'Text to translate');
+
+Context-aware translation. Allows the same text to be translated differently
+based on context (e.g., 'File' in a menu vs 'File' as a document type).
+
+=cut
+
 sub __p {
     my ( $msgctxt, $msgid ) = @_;
 
@@ -143,6 +230,14 @@ sub __p {
     return _gettext( \&pgettext, [ $msgctxt, $msgid ] );
 }
 
+=head2 __px
+
+    my $translated = __px('context', 'Hello {name}', name => 'World');
+
+Context-aware translation with variable substitution.
+
+=cut
+
 sub __px {
     my ( $msgctxt, $msgid, %vars ) = @_;
 
@@ -152,6 +247,14 @@ sub __px {
     return _gettext( \&pgettext, [ $msgctxt, $msgid ], %vars );
 }
 
+=head2 __np
+
+    my $translated = __np('context', 'one item', '{count} items', $count);
+
+Context-aware plural translation.
+
+=cut
+
 sub __np {
     my ( $msgctxt, $msgid, $msgid_plural, $count ) = @_;
 
@@ -162,6 +265,14 @@ sub __np {
     return _gettext( \&npgettext, [ $msgctxt, $msgid, $msgid_plural, $count ] );
 }
 
+=head2 __npx
+
+    my $translated = __npx('context', 'one item', '{count} items', $count, count => $count);
+
+Context-aware plural translation with variable substitution.
+
+=cut
+
 sub __npx {
     my ( $msgctxt, $msgid, $msgid_plural, $count, %vars ) = @_;
 
@@ -172,18 +283,51 @@ sub __npx {
     return _gettext( \&npgettext, [ $msgctxt, $msgid, $msgid_plural, $count ], %vars );
 }
 
+=head2 N__
+
+    my $msgid = N__('Text for later translation');
+
+No-operation translation marker. Returns the original text unchanged but marks
+it for extraction by translation tools.
+
+=cut
+
 sub N__ {
     return $_[0];
 }
 
+=head2 N__n
+
+    my $msgid = N__n('singular', 'plural');
+
+No-operation plural translation marker.
+
+=cut
+
 sub N__n {
     return $_[0];
 }
 
+=head2 N__p
+
+    my $msgid = N__p('context', 'Text for later translation');
+
+No-operation context translation marker.
+
+=cut
+
 sub N__p {
     return $_[1];
 }
 
+=head2 N__np
+
+    my $msgid = N__np('context', 'singular', 'plural');
+
+No-operation context plural translation marker.
+
+=cut
+
 sub N__np {
     return $_[1];
 }
@@ -323,4 +467,23 @@ sub available_locales {
     return \@available_locales;
 }
 
+=head1 AUTHOR
+
+Koha Development Team
+
+=head1 COPYRIGHT
+
+Copyright 2012-2014 BibLibre
+
+=head1 LICENSE
+
+This file is part of Koha.
+
+Koha is free software; you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation; either version 3 of the License, or (at your option) any later
+version.
+
+=cut
+
 1;