From 6c2d7d2a75cf036ea4fbdefa28c5da74fc4bcd7b Mon Sep 17 00:00:00 2001 From: Martin Renvoize Date: Thu, 26 Jun 2025 17:41:00 +0100 Subject: [PATCH] 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. --- Koha/I18N.pm | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 164 insertions(+), 1 deletion(-) diff --git a/Koha/I18N.pm b/Koha/I18N.pm index 0be3960ae05..3fbbabe685f 100644 --- a/Koha/I18N.pm +++ b/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]; } @@ -235,7 +379,7 @@ sub _expand { Returns an arrayref of available system locales for use in system preferences. Each locale is a hashref with: - - C: The locale identifier (e.g., 'en_US.utf8', 'default') + - C: The locale identifier (e.g., 'en_US.utf8', 'default') - C: Human-readable description (e.g., 'English (United States) - en_US.utf8') Always includes 'default' as the first option. Additional locales are detected @@ -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; -- 2.49.0