Changeset 2292

Timestamp:

12/30/08 17:26:30 (3 years ago)

Author:

adamk

Message:

Creating proposed data structure to serve as the basis for second-generation locale support.

File:

• trunk/Padre/lib/Padre/Locale.pm (modified) (4 diffs)

trunk/Padre/lib/Padre/Locale.pm

@@ -1 +1 @@
 package Padre::Locale;
 
-# Padre::Locale provides a variety of locale and encoding support functions,
-# to prevent locale code (which can be fairly complex) from being scattered
-# all over the codebase.
-#
-# Note: Normally, namespace convention is that modules outside of Padre::Wx
+=pod
+
+=head1 NAME
+
+Padre::Locale - Locale support for Padre
+
+=head1 DESCRIPTION
+
+B<Padre::Locale> is a utility library that implements locale and encoding
+support for the L<Padre> editor, and serves as an integration point between
+the various identifier systems (Wx identifiers, ISO639, RFC3066, RFC4646)
+
+The module implements a collection of public functions that can be called
+by various parts of the editor to get locale and encoding information.
+
+None of the functions in B<Padre::Locale> are exported. Because the need
+for encoding and locale functionality is very high in a user-facing
+application like Padre, the resulting quantity of exports would be very
+very high.
+
+Forcing all calls to the functions to be fully referenced assists in
+reducing the complexity of the Perl symbol table (saving a small amount of
+memory) and serves to improve maintainability, as there can always be
+certainty about where a particular function is being called from.
+
+=head1 FUNCTIONS
+
+TO BE COMPLETED
+
+=cut
+
+use 5.008;
+use strict;
+use warnings;
+
+# NOTE: Normally, namespace convention is that modules outside of Padre::Wx
 # should not implement anything using Wx modules.
 # We make an exception in this case, because we're only using the locale
 # logic in Wx, which isn't related to widgets anyway.
-
-use 5.008;
-use strict;
-use warnings;
 use Padre::Util ();
 use Padre::Wx   ();
@@ -23 +50 @@
 
 #####################################################################
-# Locale Support
+# Locale 2.0 Tables
+
+use constant RFC4646_DEFAULT => 'en-gb';
+
+# The RFC4646 table is the primary language data table and contains
+# mappings from a Padre-supported language to all the relevant data
+# about that language.
+# According to the RFC all identifiers are case-insensitive, but for
+# simplicity (for now) we list them all as lower-case.
+my %RFC4646 = (
+    # The default language for Padre is "United Kingdom English"
+    # The most common English dialect, used not only in the UK,
+    # but also other Commonwealth countries such as Australia,
+    # New Zealand, India, and Canada (sort of...)
+    # The following entry for it is heavily commented for
+    # documentation purposes.
+    'en-gb' => {
+        # REQUIRED: The gettext msgid for the language.
+        gettext   => 'English (British)',
+
+        # REQUIRED: Mapping to ISO 639 language tag.
+        # Used by Padre's first-generation locale support
+        # This should be lowercase.
+        iso639    => 'en',
+
+        # OPTIONAL: Mapping to the ISO 3166 country code.
+        # This should be uppercase.
+        iso3166   => 'GB',
+
+        # REQUIRED: The wxWidgets language (integer) identifier.
+        wxid      => Wx::wxLANGUAGE_ENGLISH_UK,
+
+        # OPTIONAL: The wxWidgets catalog file to use.
+        # Having this as an explicit file name simplified the
+        # transition from the old to the new style.
+        wxcatalog => 'en.mo',
+
+        # OPTIONAL: Recommended language fallback sequence.
+        # This is an ordered list of alternative languages
+        # that Padre should try to use if no first-class
+        # support is available for this language.
+        # This is mainly used to allow closest-dialect support.
+        # For example, if full support for "Portugese Portugese"
+        # is not available, we first attempt to use
+        # "Brazillian Portugese" first, before falling back on
+        # "American English" and only then the default.
+        # Entries in the fallback list express intent, and
+        # they do not need to have an entry in %RFC4646.
+        fallback  => [ ],
+    },
+
+    # Example entry for an language which is not supported directly,
+    # but which Padre is aware of.
+    'en-au' => {
+        gettext  => 'English (Australian)',
+        iso639   => 'en',
+        iso3166  => 'AU',
+        wxid     => Wx::wxLANGUAGE_ENGLISH_AUSTRALIAN,
+        # Even though en-gb is the default language, in this
+        # specific case there is a clearly expressed desire for
+        # this fallback path.
+        # If we are ever forced for technical reasons to move to
+        # using en-us as a default, this group would explicitly
+        # wish to retain the final fallback to en-gb.
+        fallback => [ 'en-nz', 'en-gb' ],
+    },
+
+    # The remaining languages are listed sorted by identifier.
+    # NOTE: Please do not populate entries into this list unless
+    # you are a native speaker of a particular language and are
+    # fully aware of any 
+
+    'en-nz' => {
+        gettext  => 'English (New Zealand)',
+        iso639   => 'en',
+        iso3166  => 'NZ',
+        wxid     => Wx::wxLANGUAGE_NEW_ZEALAND,
+        fallback => [ 'en-au', 'en-gb' ], # The en-au is debatable
+    },
+
+    'en-us' => {
+        gettext  => 'English (US)',
+        iso639   => 'en',
+        iso3166  => 'US',
+        wxid     => Wx::wxLANGUAGE_ENGLISH_US,
+    },
+
+    
+);
+
+
+
+
+
+#####################################################################
+# Locale 1.0 Support
 
 use constant DEFAULT_LOCALE => 'en';
-
 
 my %SHORTNAME = (
     Wx::wxLANGUAGE_ARABIC()        => 'ar',
     Wx::wxLANGUAGE_GERMAN()        => 'de',
+
+    # This should be addressed by the fallback system
     Wx::wxLANGUAGE_ENGLISH_US()    => 'en',
+
     Wx::wxLANGUAGE_FRENCH()        => 'fr',
     Wx::wxLANGUAGE_HEBREW()        => 'he',
@@ -39 +163 @@
     Wx::wxLANGUAGE_RUSSIAN()       => 'ru',
     Wx::wxLANGUAGE_DUTCH()         => 'nl',
-    Wx::wxLANGUAGE_PORTUGUESE() => 'pt', # probably should be 'pt_br'
-        Wx::wxLANGUAGE_SPANISH()    => 'es',
+
+    # Probably should be a separate 'pt_br'
+    # (With apologies to the Portugese)
+    Wx::wxLANGUAGE_PORTUGUESE()    => 'pt',
+
+        Wx::wxLANGUAGE_SPANISH()       => 'es',
 );
 
@@ -47 +175 @@
 # LANGUAGES hash needs to be here in order
 # the get the run-time language change for these words too.
+my %LANGUAGES = (
+    ar => Wx::gettext('Arabic'),
+    de => Wx::gettext('German'),
+    en => Wx::gettext('English'),
+    fr => Wx::gettext('French'),
+    he => Wx::gettext('Hebrew'),
+    hu => Wx::gettext('Hungarian'),
+    ko => Wx::gettext('Korean'),
+    it => Wx::gettext('Italian'),
+    ru => Wx::gettext('Russian'),
+    nl => Wx::gettext('Dutch'),
+    pt => Wx::gettext('Portuguese'), # Actually brazilian, which is a bug
+        es => Wx::gettext('Spanish'),
+);
+
+# TODO: The need for direct access to the table indicates a failure
+#       on the part of Padre::Locale to provide sufficiently useful
+#       functions. Second-generation locale support has data that is
+#       too complex to be reasonably useful to external consumers, so
+#       we need to fix that by providing more direct functions.
 sub languages {
-    return (
-        ar => Wx::gettext('Arabic'),
-        de => Wx::gettext('German'),
-        en => Wx::gettext('English'),
-        fr => Wx::gettext('French'),
-        he => Wx::gettext('Hebrew'),
-        hu => Wx::gettext('Hungarian'),
-        ko => Wx::gettext('Korean'),
-        it => Wx::gettext('Italian'),
-        ru => Wx::gettext('Russian'),
-        nl => Wx::gettext('Dutch'),
-        pt => Wx::gettext('Portuguese'), # brazilian
-                es => Wx::gettext('Spanish'),
-    );
+    return %LANGUAGES;
 }