=head1 NOM DateTime::Locale - Support de la localisation pour les dates-heures de C =head1 RÉSUMÉ use DateTime::Locale; my $loc = DateTime::Locale->load('en_GB'); print $loc->native_locale_name, "\n", $loc->long_datetime_format, "\n"; # mais la plupart du temps, rien de plus que... my $dt = DateTime->now( locale => 'fr' ); print "Aujourd'hui le mois est " . $dt->month_name, "\n": =head1 DESCRIPTION C est essentiellement un générateur pour des sous-classes de localisation. Le module fournit également quelques fonctions fournissant de l'information relative aux localisations disponibles. Si vous voulez savoir quelles méthodes les objets de localisation offrent, merci de vous reporter à la documentation de C. =head1 UTILISATION Ce module fournit les méthodes de classe S =over 4 =item * load( $locale_id | $locale_name | $alias ) Renvoie l'objet de localisation pour l'identifiant de localisation, son nom ou son alias (cf. la documentation de C pour avoir la liste des noms et des identifiants connus). Le nom peut être le nom anglophone ou le nom local. Si le nom n'est pas connu, le module effectue une recherche par défaut pour obtenir un nom convenable en remplacement. La priorité des défauts est la S langue_territoire_variante langue_territoire langue Prenons l'exemple d'un nom de localisation C. La recherche par défaut S es_XX_INCONNU # échec, localisation inconnue es_XX # échec, localisation inconnue es # trouvé, la localisation "es" est renvoyée comme étant # la mieux appropriée pour le nom demandé. Si aucun nom de remplacement n'est trouvé, le module s'arrête en erreur. Notez que si vous fournissez un B à cette méthode, la méthode C de l'objet renvoyé sera B égale à la valeur que vous avez donnée, même si cette valeur était un alias pour un autre identifiant. Cela correspond à une volonté de compatibilité ascendante, en prévision du cas où ce qui est actuellement un alias deviendrait un identifiant de localisation à part entière dans le futur. Cela signifie que la valeur de C et le nom de la classe de l'objet peuvent ne pas coïncider. Les objets de localisation sont conservés en mémoire cache, ce qui fait que B. L'appel de C, C, ou de C nettoie la mémoire cache. =item * ids my @ids = DateTime::Locale->ids; my $ids = DateTime::Locale->ids; Renvoie une liste des identifiants de localisation disponibles (ou la référence à un tableau en contexte scalaire). La liste n'est pas triée et elle ne contient pas d'alias. =item * names my @names = DateTime::Locale->names; my $names = DateTime::Locale->names; Renvoie une liste des noms de localisation anglophones disponibles (ou la référence à un tableau en contexte scalaire). La liste n'est pas triée. =item * native_names my @names = DateTime::Locale->native_names; my $names = DateTime::Locale->native_names; Renvoie une liste des noms de localisation disponibles (ou la référence à un tableau en contexte scalaire). Les noms sont les noms locaux, codés en utf8. La liste n'est pas triée. S :> de nombreuses données de localisation sont traduites de façon incomplète. Il se peut que les noms locaux contiennent encore un peu d'anglais. =item * add_aliases ( $alias1 => $id1, $alias2 => $id2, ... ) Ajoute un alias à un identifiant existant. Cela permet de charger des données de localisation en spécifiant l'alias au lieu de l'identifiant ou du nom. Il est possible d'associer plusieurs alias à un même identifiant. Si l'identifiant soumis n'a pas été enregistré par C et ne figure pas dans L, le module s'arrête en erreur. DateTime::Locale->add_aliases( LastResort => 'es_ES' ); # Equivalent à DateTime::Locale->load('es_ES'); DateTime::Locale->load('LastResort'); Vous pouvez également transmettre la référence d'un hachage à cette S DateTime::Locale->add_aliases( { Default => 'en_GB', Alternative => 'en_US', LastResort => 'es_ES' } ); =item * remove_alias( $alias ) Supprime l'alias d'un identifiant de S renvoie une valeur S<« vraie »> si l'alias existait bel et bien. DateTime::Locale->add_aliases( LastResort => 'es_ES' ); # Equivalent à DateTime::Locale->load('es_ES'); DateTime::Locale->load('LastResort'); DateTime::Locale->remove_alias('LastResort'); # S'arrête en erreur, 'LastResort' n'existe plus DateTime::Locale->load('LastResort'); =item * register( { ... }, { ... } ) Cette méthode vous permet de répertorier des informations de localisation spécifiques auprès du module. Pour enregistrer une seule variante, vous pouvez transmettre un hachage à la méthode. Pour enregistrer plusieurs variantes, vous devez transmettre un tableau de références de hachage. Tant qu'elles ne sont pas répertoriées, les variantes spécifiques ne peuvent pas être instanciées par C et elles ne feront pas partie des listes renvoyées par les méthodes d'interrogation telles que C ou C. register( id => $locale_id, en_language => ..., # quelque chose comme 'English' ou 'Afar', # toutes les autres clés sont facultatives ; ce sont : en_territory => ..., en_variant => ..., native_language => ..., native_territory => ..., native_variant => ..., # Facultatif - la valeur par défault est DateTime::Locale::$locale_id class => $class_name, replace => $boolean ) L'identifiant et le nom anglais de la variante sont obligatoires et il est vivement recommandé d'utiliser les formats suivants quand c'est S id : languageId[_territoryId[_variantId]] avec : languageId = code langage ISO 639 en minuscules -- si possible, utiliser 639-1 en priorité par rapport à 639-2. territoryId = code territoire ISO 3166 en majuscules -- si possible, utiliser 3166-1 en priorité par rapport à 3166-2. variantId = code variante en majuscules -- mettez-y ce que vous voulez, étant donné que c'est généralement ce code qui permet d'identifier de manière unique la variante. Vous ne pouvez pas utiliser les caractères S<« @ »> ou S<« = »> dans les identifiants de localisation, ils sont réservés pour une utilisation ultérieure. Le souligné (S<« _ »>) est le séparateur de composants et ne doit pas être utilisé pour un autre besoin. Si vous transmettez des paramètres C, ils doivent être encodés en utf8. S'il n'est pas renseigné, le nom natif sera identique au nom anglais. Si vous donnez un nom de classe, ce doit être le nom complet de votre module spécifique. Si vous n'indiquez pas de nom de classe, le module sera une sous-classe de C. Exemples : DateTime::Locale->register ( id => 'en_GB_RIDAS', en_language => 'English', en_territory => 'United Kingdom', en_variant => 'Ridas Custom Locale', ); # Renvoie une instance de la classe DateTime::Locale::en_GB_RIDAS my $l = DateTime::Locale->load('en_GB_RIDAS'); DateTime::Locale->register ( id => 'hu_HU', en_language => 'Hungarian', en_territory => Hungary', native_language => 'Magyar', native_territory => 'Magyarország', ); # Renvoie une instance de la classe DateTime::Locale::hu_HU my $l = DateTime::Locale->load('hu_HU'); DateTime::Locale->register ( id => 'en_GB_RIDAS', name => 'English United Kingdom Ridas custom locale', class => 'Ridas::Locales::CustomGB', ); # Renvoie une instance de la classe Ridas::Locales::CustomGB # MAIS PAS Ridas::Locales::Custom::en_GB_RIDAS ! my $l = DateTime::Locale->load('en_GB_RIDAS'); Si vous répertoriez une localisation qui existe déjà, vous devez attribuer une valeur S<« vraie »> au paramètre C, sinon, le module s'arrête en erreur. Le nom complet de la localisation est généré en réunissant le nom du langage, celui du territoire et celui de la variante, séparés par un blanc. Cela signifie que dans le premier exemple, le nom anglais et le nom natif seraient S<« English United Kingdom Ridas Custom Locale »>, et que dans le deuxième exemple, le nom anglais complet est S<« Hungarian Hungary »>, tandis que le nom natif complet est S<« Magyar Magyarország »>. Il est possible de charger la localisation en utilisant l'un de ces noms complets (anglais et natif), par la méthode C. =back =head1 COMMENT CRÉER DES LOCALISATIONS PERSONNELLES Vous pouvez créer des localisations personnelles de deux S =over 4 =item 1. En créant une sous-classe d'une classe de localisation existante et en codant uniquement ce qui est différent. =item 2. En créant de toutes pièces une nouvelle classe. =back Dans un cas comme dans l'autre, la localisation DOIT êre répertoriée avant utilisation. =head2 Sous-classe d'une classe existante L'exemple ci-dessous crée une sous-classe de la localisation anglaise du Royaume-Uni, pour donner des formats différents de date-S package Ridas::Locale::en_GB_RIDAS1; use strict; use DateTime::Locale::en_GB; @Ridas::Locale::en_GB_RIDAS1::ISA = qw ( DateTime::Locale::en_GB ); my $locale_id = 'en_GB_RIDAS1'; my $date_formats = { "full" => "%A %{day} %B %{ce_year}", "long" => "%{day} %B %{ce_year}", "medium" => "%{day} %b %{ce_year}", "short" => "%{day}/%m/%y", }; my $time_formats = { "full" => "%H h %{minute} %{time_zone_short_name}", "long" => "%{hour12}:%M:%S %p", "medium" => "%{hour12}:%M:%S %p", "short" => "%{hour12}:%M %p", }; sub date_formats { $date_formats } sub time_formats { $time_formats } 1; Et maintenant, répertorions la S DateTime::Locale->register ( id => 'en_GB_RIDAS1', # nom, territoire et variante comme décrit dans la documentation de register() class => 'Ridas::Locale::en_GB_RIDAS1' ); =head2 Création complète d'une nouvelle localisation Une nouvelle classe de localisation doit comporter les méthodes S id month_names month_abbreviations day_names day_abbreviations am_pms eras date_formats time_formats datetime_format_pattern_order date_parts_order _default_date_format_length _default_time_format_length Cf. C pour la description de chaque méthode et jetez un coup d'oeil à F qui donne un exemple d'implémentation complète. Vous pouvez, si vous le souhaitez, créer votre sous-classe comme étant une sous-classe de C, mais cela n'a rien d'obligatoire. Et une fois la création effectuée, n'oubliez pas de la S Bien sûr, vous pouvez toujours coder l'appel à C au sein du module lui-même et vous contenter de charger le module avant de l'utiliser. =head1 MÉTHODES OBJET DES LOCALISATIONS Tous les objets héritant de C proposent un certain nombre de méthodes. Toutes les localisations incluses dans la distribution sont des sous-classes de C. Les méthodes suivantes permettent d'obtenir de l'information sur le nom ou l'identifiant de la localisation. =over 4 =item * id L'identifiant complet, quelque chose du genre S<« en_US »>. =item * language_id La partie langage de l'identifiant, comme S<« en »>. =item * territory_id La partie territoire de l'identifiant, comme S<« US »>. =item * variant_id La portion variante de l'identifiant, comme S<« PREEURO »>. =item * name Le nom complet de la localisation, qui comporte toujours au moins un nom de langage et qui comporte de manière facultative un nom de territoire et un nom d'option. Quelque chose du genre S<« English United States »>. La valeur renvoyée est toujours en anglais. =item * language =item * territory =item * variant Les éléments correspondants du nom de la localisation, comme S<« English »> ou S<« United States »>. =item * native_name Le nom complet de la localisation, exprimé dans sa propre langue et encodé en UTF-8. =item * native_language =item * native_territory =item * native_variant Les éléments correspondants du nom de la localisation, encodés en UTF-8. =back Les méthodes suivantes portent sur un objet C et renvoient un nom en langue locale. =over 4 =item * month_name ($dt) Nom du mois =item * month_abbreviation ($dt) Nom abrégé du mois =item * day_name ($dt) Nom du jour de la semaine =item * day_abbreviation ($dt) Nom abrégé du jour de la semaine =item * am_pm ($dt) Mention permettant de différentier le matin de l'après-midi. =back Les méthodes suivantes renvoient des chaînes de format à l'intention de la méthode C de C. =over 4 =item * full_date_format =item * long_date_format =item * medium_date_format =item * short_date_format =item * full_time_format =item * long_time_format =item * medium_time_format =item * short_time_format =item * full_datetime_format =item * long_datetime_format =item * medium_datetime_format =item * short_datetime_format =back Les méthodes suivantes donnent la longueur par défaut des S =over 4 =item default_date_format_length =item default_time_format_length Ces méthodes renvoient C (complet), C (long), C (intermédiaire) ou C (court) pour indiquer quel est le format de date et le format d'heure par défaut. Lorsqu'un objet est créé, la valeur par défaut est déterminée par les données de localisation ICU. =item set_default_date_format_length ($length) =item set_default_time_format_length ($length) Ces méthodes permettent de modifier la valeur par défaut de la longueur du format de date ou d'heure. =back Les méthodes suivantes permettent d'obtenir les données brutes de localisation d'un objet. Si la méthode renvoie une référence, il s'agit d'une référence aux données brutes. Donc, si vous modifiez les données, cela modifie l'objet lui-même. Commencez donc par effectuer la copie des données référencées. =over 4 =item * month_names Renvoie la référence à un tableau contenant le nom complet des mois, janvier étant en première position. =item * month_abbreviations Renvoie la référence à un tableau contenant les abréviations des mois, janvier étant en première position. =item * day_names Renvoie la référence à un tableau contenant le nom complet des jours de la semaine, avec lundi en première position. =item * day_abbreviations Renvoie la référence à un tableau contenant les abréviations des jours de la semaine, avec lundi en première position. =item * am_pms Renvoie la référence à un tableau contenant la version locale de la chaîne S<« AM »> indiquant le matin, ainsi que la version locale de S<« PM »> pour l'après-midi. =item * date_formats Renvoie la référence d'un hachage contenant les formats de date utilisés dans cette localisation. Les clés du hachage sont C, C, C et C. =item * time_formats Renvoie la référence d'un hachage contenant les formats d'heure utilisés dans cette localisation. Les clés du hachage sont C, C, C et C. =item * date_before_time Renvoie un booléen indiquant si la date s'affiche avant l'heure (S<« vrai »>) ou si l'heure s'affiche avant la date (S<« faux »>) lorsqu'il faut mettre en forme une date-heure complète. =item * date_parts_order Renvoie une chaîne indiquant l'ordre dans lequel apparaissent les éléments d'une date de la forme XX/YY/ZZ. Les valeurs possibles sont S<« dmy »>, S<« mdy »>, S<« ymd »> et S<« ydm »> où S<« y »> représente l'année, S<« m »> représente le mois et S<« d »> représente le jour. =back =head1 SUPPORT Gardez à l'esprit que toutes les données de localisation ont été générées à partir des éléments fournis par le projet I (à l'origine I). Les données I incomplètes et I des erreurs pour certaines localisations. Si vous constatez des erreurs dans les données, merci de vérifier d'abord la source de données primaire, puis de soumettre le rapport de bug à cette source primaire, via le système I du projet ICU à l'adresse L. Une fois ces erreurs confirmées, merci de communiquer le compte-rendu d'erreur, ainsi que les corrections, à la liste de diffusion DateTime, C. Le support de ce module est assuré par la liste de diffusion C. Cf. http://lists.perl.org/ pour les détails. Si vous ne pensez pas maîtriser suffisamment la langue anglaise, faites-vous aider par l'un de vos proches ou éventuellement par le traducteur. =head1 AUTEURS Richard Evans (C arobase C point C) et Dave Rolsky (C arobase C point C). Ces modules sont basés sur les modules C, lequels sont à leur tour basés sur les modules C provenant de la distribution C de Graham Barr. Merci à Rick Measham pour avoir fourni les routines de conversion de Java vers C, routines utilisées lors de la génération des locales. =head1 TRADUCTION La traduction concerne la version 0.09 de C. Traduit le 2004-07-20 par Jean Forget (adresse C chez C point C). =head1 COPYRIGHT Copyright (c) 2003 Richard Evans pour la version originale. Tous droits réservés. Ce logiciel est un logiciel S vous pouvez le redistribuer et le modifier aux mêmes conditions que Perl lui-même. Vous pouvez trouver le texte complet de la licence (en anglais) dans le fichier F inclus avec le module. Les modules de localisation dans le répertoire C ont été générés à partir de données provenant du projet I, cf. C pour la licence des données ICU. Copyright (c) 2004 Jean Forget et les Mongueurs de Perl pour la traduction française. Tous droits réservés. =head1 VOIR ÉGALEMENT L La liste de distribution C http://datetime.perl.org/ http://datetime.mongueurs.net/ =cut