{
    "mode": "perldoc",
    "parameter": "Locale::Maketext",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Locale%3A%3AMaketext/json",
    "generated": "2026-08-20T21:20:43Z",
    "synopsis": "package MyProgram;\nuse strict;\nuse MyProgram::L10N;\n# ...which inherits from Locale::Maketext\nmy $lh = MyProgram::L10N->gethandle() || die \"What language?\";\n...\n# And then any messages your program emits, like:\nwarn $lh->maketext( \"Can't open file [1]: [2]\\n\", $f, $! );\n...",
    "sections": {
        "NAME": {
            "content": "Locale::Maketext - framework for localization\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "package MyProgram;\nuse strict;\nuse MyProgram::L10N;\n# ...which inherits from Locale::Maketext\nmy $lh = MyProgram::L10N->gethandle() || die \"What language?\";\n...\n# And then any messages your program emits, like:\nwarn $lh->maketext( \"Can't open file [1]: [2]\\n\", $f, $! );\n...\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "It is a common feature of applications (whether run directly, or via the Web) for them to be\n\"localized\" -- i.e., for them to a present an English interface to an English-speaker, a German\ninterface to a German-speaker, and so on for all languages it's programmed with.\nLocale::Maketext is a framework for software localization; it provides you with the tools for\norganizing and accessing the bits of text and text-processing code that you need for producing\nlocalized applications.\n\nIn order to make sense of Maketext and how all its components fit together, you should probably\ngo read Locale::Maketext::TPJ13, and *then* read the following documentation.\n\nYou may also want to read over the source for \"File::Findgrep\" and its constituent modules --\nthey are a complete (if small) example application that uses Maketext.\n",
            "subsections": []
        },
        "QUICK OVERVIEW": {
            "content": "The basic design of Locale::Maketext is object-oriented, and Locale::Maketext is an abstract\nbase class, from which you derive a \"project class\". The project class (with a name like\n\"TkBocciBall::Localize\", which you then use in your module) is in turn the base class for all\nthe \"language classes\" for your project (with names \"TkBocciBall::Localize::it\",\n\"TkBocciBall::Localize::en\", \"TkBocciBall::Localize::fr\", etc.).\n\nA language class is a class containing a lexicon of phrases as class data, and possibly also\nsome methods that are of use in interpreting phrases in the lexicon, or otherwise dealing with\ntext in that language.\n\nAn object belonging to a language class is called a \"language handle\"; it's typically a\nflyweight object.\n\nThe normal course of action is to call:\n\nuse TkBocciBall::Localize;  # the localization project class\n$lh = TkBocciBall::Localize->gethandle();\n# Depending on the user's locale, etc., this will\n# make a language handle from among the classes available,\n# and any defaults that you declare.\ndie \"Couldn't make a language handle??\" unless $lh;\n\nFrom then on, you use the \"maketext\" function to access entries in whatever lexicon(s) belong to\nthe language handle you got. So, this:\n\nprint $lh->maketext(\"You won!\"), \"\\n\";\n\n...emits the right text for this language. If the object in $lh belongs to class\n\"TkBocciBall::Localize::fr\" and %TkBocciBall::Localize::fr::Lexicon contains \"(\"You won!\" => \"Tu\nas gagné!\")\", then the above code happily tells the user \"Tu as gagné!\".\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Locale::Maketext offers a variety of methods, which fall into three categories:\n\n*   Methods to do with constructing language handles.\n\n*   \"maketext\" and other methods to do with accessing %Lexicon data for a given language handle.\n\n*   Methods that you may find it handy to use, from routines of yours that you put in %Lexicon\nentries.\n\nThese are covered in the following section.\n",
            "subsections": [
                {
                    "name": "Construction Methods",
                    "content": "These are to do with constructing a language handle:\n\n*   $lh = YourProjClass->gethandle( ...langtags... ) || die \"lg-handle?\";\n\nThis tries loading classes based on the language-tags you give (like \"(\"en-US\", \"sk\", \"kon\",\n\"es-MX\", \"ja\", \"i-klingon\")\", and for the first class that succeeds, returns\nYourProjClass::*language*->new().\n\nIf it runs thru the entire given list of language-tags, and finds no classes for those exact\nterms, it then tries \"superordinate\" language classes. So if no \"en-US\" class (i.e.,\nYourProjClass::enus) was found, nor classes for anything else in that list, we then try its\nsuperordinate, \"en\" (i.e., YourProjClass::en), and so on thru the other language-tags in the\ngiven list: \"es\". (The other language-tags in our example list: happen to have no\nsuperordinates.)\n\nIf none of those language-tags leads to loadable classes, we then try classes derived from\nYourProjClass->fallbacklanguages() and then if nothing comes of that, we use classes named\nby YourProjClass->fallbacklanguageclasses(). Then in the (probably quite unlikely) event\nthat that fails, we just return undef.\n\n*   $lh = YourProjClass->gethandle() || die \"lg-handle?\";\n\nWhen \"gethandle\" is called with an empty parameter list, magic happens:\n\nIf \"gethandle\" senses that it's running in program that was invoked as a CGI, then it tries\nto get language-tags out of the environment variable \"HTTPACCEPTLANGUAGE\", and it pretends\nthat those were the languages passed as parameters to \"gethandle\".\n\nOtherwise (i.e., if not a CGI), this tries various OS-specific ways to get the language-tags\nfor the current locale/language, and then pretends that those were the value(s) passed to\n\"gethandle\".\n\nCurrently this OS-specific stuff consists of looking in the environment variables \"LANG\" and\n\"LANGUAGE\"; and on MSWin machines (where those variables are typically unused), this also\ntries using the module Win32::Locale to get a language-tag for whatever language/locale is\ncurrently selected in the \"Regional Settings\" (or \"International\"?) Control Panel. I welcome\nfurther suggestions for making this do the Right Thing under other operating systems that\nsupport localization.\n\nIf you're using localization in an application that keeps a configuration file, you might\nconsider something like this in your project class:\n\nsub gethandleviaconfig {\nmy $class = $[0];\nmy $chosenlanguage = $Configsettings{'language'};\nmy $lh;\nif($chosenlanguage) {\n$lh = $class->gethandle($chosenlanguage)\n|| die \"No language handle for \\\"$chosenlanguage\\\"\"\n. \" or the like\";\n} else {\n# Config file missing, maybe?\n$lh = $class->gethandle()\n|| die \"Can't get a language handle\";\n}\nreturn $lh;\n}\n\n*   $lh = YourProjClass::langname->new();\n\nThis constructs a language handle. You usually don't call this directly, but instead let\n\"gethandle\" find a language class to \"use\" and to then call ->new on.\n\n*   $lh->init();\n\nThis is called by ->new to initialize newly-constructed language handles. If you define an\ninit method in your class, remember that it's usually considered a good idea to call\n$lh->SUPER::init in it (presumably at the beginning), so that all classes get a chance to\ninitialize a new object however they see fit.\n\n*   YourProjClass->fallbacklanguages()\n\n\"gethandle\" appends the return value of this to the end of whatever list of languages you\npass \"gethandle\". Unless you override this method, your project class will inherit\nLocale::Maketext's \"fallbacklanguages\", which currently returns \"('i-default', 'en',\n'en-US')\". (\"i-default\" is defined in RFC 2277).\n\nThis method (by having it return the name of a language-tag that has an existing language\nclass) can be used for making sure that \"gethandle\" will always manage to construct a\nlanguage handle (assuming your language classes are in an appropriate @INC directory). Or\nyou can use the next method:\n\n*   YourProjClass->fallbacklanguageclasses()\n\n\"gethandle\" appends the return value of this to the end of the list of classes it will try\nusing. Unless you override this method, your project class will inherit Locale::Maketext's\n\"fallbacklanguageclasses\", which currently returns an empty list, \"()\". By setting this to\nsome value (namely, the name of a loadable language class), you can be sure that\n\"gethandle\" will always manage to construct a language handle.\n\nThe \"maketext\" Method\nThis is the most important method in Locale::Maketext:\n\n$text = $lh->maketext(I<key>, ...parameters for this phrase...);\n\nThis looks in the %Lexicon of the language handle $lh and all its superclasses, looking for an\nentry whose key is the string *key*. Assuming such an entry is found, various things then\nhappen, depending on the value found:\n\nIf the value is a scalarref, the scalar is dereferenced and returned (and any parameters are\nignored).\n\nIf the value is a coderef, we return &$value($lh, ...parameters...).\n\nIf the value is a string that *doesn't* look like it's in Bracket Notation, we return it (after\nreplacing it with a scalarref, in its %Lexicon).\n\nIf the value *does* look like it's in Bracket Notation, then we compile it into a sub, replace\nthe string in the %Lexicon with the new coderef, and then we return &$newsub($lh,\n...parameters...).\n\nBracket Notation is discussed in a later section. Note that trying to compile a string into\nBracket Notation can throw an exception if the string is not syntactically valid (say, by not\nbalancing brackets right.)\n\nAlso, calling &$coderef($lh, ...parameters...) can throw any sort of exception (if, say, code in\nthat sub tries to divide by zero). But a very common exception occurs when you have Bracket\nNotation text that says to call a method \"foo\", but there is no such method. (E.g., \"You have\n[quatn,1,ball].\" will throw an exception on trying to call $lh->quatn($[1],'ball') -- you\npresumably meant \"quant\".) \"maketext\" catches these exceptions, but only to make the error\nmessage more readable, at which point it rethrows the exception.\n\nAn exception *may* be thrown if *key* is not found in any of $lh's %Lexicon hashes. What happens\nif a key is not found, is discussed in a later section, \"Controlling Lookup Failure\".\n\nNote that you might find it useful in some cases to override the \"maketext\" method with an\n\"after method\", if you want to translate encodings, or even scripts:\n\npackage YrProj::zhcn; # Chinese with PRC-style glyphs\nuse base ('YrProj::zhtw');  # Taiwan-style\nsub maketext {\nmy $self = shift(@);\nmy $value = $self->maketext(@);\nreturn Chineeze::taiwan2mainland($value);\n}\n\nOr you may want to override it with something that traps any exceptions, if that's critical to\nyour program:\n\nsub maketext {\nmy($lh, @stuff) = @;\nmy $out;\neval { $out = $lh->SUPER::maketext(@stuff) };\nreturn $out unless $@;\n...otherwise deal with the exception...\n}\n\nOther than those two situations, I don't imagine that it's useful to override the \"maketext\"\nmethod. (If you run into a situation where it is useful, I'd be interested in hearing about it.)\n\n$lh->failwith *or* $lh->failwith(*PARAM*)\n$lh->failurehandlerauto\nThese two methods are discussed in the section \"Controlling Lookup Failure\".\n\n$lh->denylist(@list) <or> $lh->blacklist(@list)\n$lh->allowlist(@list) <or> $lh->whitelist(@list)\nThese methods are discussed in the section \"Bracket Notation Security\".\n"
                },
                {
                    "name": "Utility Methods",
                    "content": "These are methods that you may find it handy to use, generally from %Lexicon routines of yours\n(whether expressed as Bracket Notation or not).\n\n$language->quant($number, $singular)\n$language->quant($number, $singular, $plural)\n$language->quant($number, $singular, $plural, $negative)\nThis is generally meant to be called from inside Bracket Notation (which is discussed\nlater), as in\n\n\"Your search matched [quant,1,document]!\"\n\nIt's for *quantifying* a noun (i.e., saying how much of it there is, while giving the\ncorrect form of it). The behavior of this method is handy for English and a few other\nWestern European languages, and you should override it for languages where it's not\nsuitable. You can feel free to read the source, but the current implementation is basically\nas this pseudocode describes:\n\nif $number is 0 and there's a $negative,\nreturn $negative;\nelsif $number is 1,\nreturn \"1 $singular\";\nelsif there's a $plural,\nreturn \"$number $plural\";\nelse\nreturn \"$number \" . $singular . \"s\";\n#\n# ...except that we actually call numf to\n#  stringify $number before returning it.\n\nSo for English (with Bracket Notation) \"...[quant,1,file]...\" is fine (for 0 it returns \"0\nfiles\", for 1 it returns \"1 file\", and for more it returns \"2 files\", etc.)\n\nBut for \"directory\", you'd want \"[quant,1,directory,directories]\" so that our elementary\n\"quant\" method doesn't think that the plural of \"directory\" is \"directorys\". And you might\nfind that the output may sound better if you specify a negative form, as in:\n\n\"[quant,1,file,files,No files] matched your query.\\n\"\n\nRemember to keep in mind verb agreement (or adjectives too, in other languages), as in:\n\n\"[quant,1,document] were matched.\\n\"\n\nBecause if 1 is one, you get \"1 document were matched\". An acceptable hack here is to do\nsomething like this:\n\n\"[quant,1,document was, documents were] matched.\\n\"\n\n$language->numf($number)\nThis returns the given number formatted nicely according to this language's conventions.\nMaketext's default method is mostly to just take the normal string form of the number\n(applying sprintf \"%G\" for only very large numbers), and then to add commas as necessary.\n(Except that we apply \"tr/,./.,/\" if $language->{'numfcomma'} is true; that's a bit of a\nhack that's useful for languages that express two million as \"2.000.000\" and not as\n\"2,000,000\").\n\nIf you want anything fancier, consider overriding this with something that uses\nNumber::Format, or does something else entirely.\n\nNote that numf is called by quant for stringifying all quantifying numbers.\n\n$language->numerate($number, $singular, $plural, $negative)\nThis returns the given noun form which is appropriate for the quantity $number according to\nthis language's conventions. \"numerate\" is used internally by \"quant\" to quantify nouns. Use\nit directly -- usually from bracket notation -- to avoid \"quant\"'s implicit call to \"numf\"\nand output of a numeric quantity.\n\n$language->sprintf($format, @items)\nThis is just a wrapper around Perl's normal \"sprintf\" function. It's provided so that you\ncan use \"sprintf\" in Bracket Notation:\n\n\"Couldn't access datanode [sprintf,%10x=~[%s~],1,2]!\\n\"\n\nreturning...\n\nCouldn't access datanode      Stuff=[thangamabob]!\n\n$language->languagetag()\nCurrently this just takes the last bit of ref($language), turns underscores to dashes, and\nreturns it. So if $language is an object of class Hee::HOO::Haw::enus,\n$language->languagetag() returns \"en-us\". (Yes, the usual representation for that language\ntag is \"en-US\", but case is *never* considered meaningful in language-tag comparison.)\n\nYou may override this as you like; Maketext doesn't use it for anything.\n\n$language->encoding()\nCurrently this isn't used for anything, but it's provided (with default value of\n\"(ref($language) && $language->{'encoding'})) or \"iso-8859-1\"\" ) as a sort of suggestion\nthat it may be useful/necessary to associate encodings with your language handles (whether\non a per-class or even per-handle basis.)\n"
                },
                {
                    "name": "Language Handle Attributes and Internals",
                    "content": "A language handle is a flyweight object -- i.e., it doesn't (necessarily) carry any data of\ninterest, other than just being a member of whatever class it belongs to.\n\nA language handle is implemented as a blessed hash. Subclasses of yours can store whatever data\nyou want in the hash. Currently the only hash entry used by any crucial Maketext method is\n\"fail\", so feel free to use anything else as you like.\n\nRemember: Don't be afraid to read the Maketext source if there's any point on which this\ndocumentation is unclear. This documentation is vastly longer than the module source itself.\n"
                }
            ]
        },
        "LANGUAGE CLASS HIERARCHIES": {
            "content": "These are Locale::Maketext's assumptions about the class hierarchy formed by all your language\nclasses:\n\n*   You must have a project base class, which you load, and which you then use as the first\nargument in the call to YourProjClass->gethandle(...). It should derive (whether directly\nor indirectly) from Locale::Maketext. It doesn't matter how you name this class, although\nassuming this is the localization component of your Super Mega Program, good names for your\nproject class might be SuperMegaProgram::Localization, SuperMegaProgram::L10N,\nSuperMegaProgram::I18N, SuperMegaProgram::International, or even SuperMegaProgram::Languages\nor SuperMegaProgram::Messages.\n\n*   Language classes are what YourProjClass->gethandle will try to load. It will look for them\nby taking each language-tag (skipping it if it doesn't look like a language-tag or\nlocale-tag!), turning it to all lowercase, turning dashes to underscores, and appending it\nto YourProjClass . \"::\". So this:\n\n$lh = YourProjClass->gethandle(\n'en-US', 'fr', 'kon', 'i-klingon', 'i-klingon-romanized'\n);\n\nwill try loading the classes YourProjClass::enus (note lowercase!), YourProjClass::fr,\nYourProjClass::kon, YourProjClass::iklingon and YourProjClass::iklingonromanized. (And\nit'll stop at the first one that actually loads.)\n\n*   I assume that each language class derives (directly or indirectly) from your project class,\nand also defines its @ISA, its %Lexicon, or both. But I anticipate no dire consequences if\nthese assumptions do not hold.\n\n*   Language classes may derive from other language classes (although they should have \"use\n*Thatclassname*\" or \"use base qw(*...classes...*)\"). They may derive from the project class.\nThey may derive from some other class altogether. Or via multiple inheritance, it may derive\nfrom any mixture of these.\n\n*   I foresee no problems with having multiple inheritance in your hierarchy of language\nclasses. (As usual, however, Perl will complain bitterly if you have a cycle in the\nhierarchy: i.e., if any class is its own ancestor.)\n",
            "subsections": []
        },
        "ENTRIES IN EACH LEXICON": {
            "content": "A typical %Lexicon entry is meant to signify a phrase, taking some number (0 or more) of\nparameters. An entry is meant to be accessed by via a string *key* in $lh->maketext(*key*,\n...parameters...), which should return a string that is generally meant for be used for \"output\"\nto the user -- regardless of whether this actually means printing to STDOUT, writing to a file,\nor putting into a GUI widget.\n\nWhile the key must be a string value (since that's a basic restriction that Perl places on hash\nkeys), the value in the lexicon can currently be of several types: a defined scalar, scalarref,\nor coderef. The use of these is explained above, in the section 'The \"maketext\" Method', and\nBracket Notation for strings is discussed in the next section.\n\nWhile you can use arbitrary unique IDs for lexicon keys (like \"minlargermaxerror\"), it is\noften useful for if an entry's key is itself a valid value, like this example error message:\n\n\"Minimum ([1]) is larger than maximum ([2])!\\n\",\n\nCompare this code that uses an arbitrary ID...\n\ndie $lh->maketext( \"minlargermaxerror\", $min, $max )\nif $min > $max;\n\n...to this code that uses a key-as-value:\n\ndie $lh->maketext(\n\"Minimum ([1]) is larger than maximum ([2])!\\n\",\n$min, $max\n) if $min > $max;\n\nThe second is, in short, more readable. In particular, it's obvious that the number of\nparameters you're feeding to that phrase (two) is the number of parameters that it *wants* to be\nfed. (Since you see 1 and a 2 being used in the key there.)\n\nAlso, once a project is otherwise complete and you start to localize it, you can scrape together\nall the various keys you use, and pass it to a translator; and then the translator's work will\ngo faster if what he's presented is this:\n\n\"Minimum ([1]) is larger than maximum ([2])!\\n\",\n=> \"\",   # fill in something here, Jacques!\n\nrather than this more cryptic mess:\n\n\"minlargermaxerror\"\n=> \"\",   # fill in something here, Jacques\n\nI think that keys as lexicon values makes the completed lexicon entries more readable:\n\n\"Minimum ([1]) is larger than maximum ([2])!\\n\",\n=> \"Le minimum ([1]) est plus grand que le maximum ([2])!\\n\",\n\nAlso, having valid values as keys becomes very useful if you set up an AUTO lexicon. AUTO\nlexicons are discussed in a later section.\n\nI almost always use keys that are themselves valid lexicon values. One notable exception is when\nthe value is quite long. For example, to get the screenful of data that a command-line program\nmight return when given an unknown switch, I often just use a brief, self-explanatory key such\nas \"USAGEMESSAGE\". At that point I then go and immediately to define that lexicon entry in the\nProjectClass::L10N::en lexicon (since English is always my \"project language\"):\n\n'USAGEMESSAGE' => <<'EOSTUFF',\n...long long message...\nEOSTUFF\n\nand then I can use it as:\n\ngetopt('oDI', \\%opts) or die $lh->maketext('USAGEMESSAGE');\n\nIncidentally, note that each class's %Lexicon inherits-and-extends the lexicons in its\nsuperclasses. This is not because these are special hashes *per se*, but because you access them\nvia the \"maketext\" method, which looks for entries across all the %Lexicon hashes in a language\nclass *and* all its ancestor classes. (This is because the idea of \"class data\" isn't directly\nimplemented in Perl, but is instead left to individual class-systems to implement as they see\nfit..)\n\nNote that you may have things stored in a lexicon besides just phrases for output: for example,\nif your program takes input from the keyboard, asking a \"(Y/N)\" question, you probably need to\nknow what the equivalent of \"Y[es]/N[o]\" is in whatever language. You probably also need to know\nwhat the equivalents of the answers \"y\" and \"n\" are. You can store that information in the\nlexicon (say, under the keys \"~answery\" and \"~answern\", and the long forms as \"~answeryes\"\nand \"~answerno\", where \"~\" is just an ad-hoc character meant to indicate to\nprogrammers/translators that these are not phrases for output).\n\nOr instead of storing this in the language class's lexicon, you can (and, in some cases, really\nshould) represent the same bit of knowledge as code in a method in the language class. (That\nleaves a tidy distinction between the lexicon as the things we know how to *say*, and the rest\nof the things in the lexicon class as things that we know how to *do*.) Consider this example of\na processor for responses to French \"oui/non\" questions:\n\nsub yorn {\nreturn undef unless defined $[1] and length $[1];\nmy $answer = lc $[1];  # smash case\nreturn 1 if $answer eq 'o' or $answer eq 'oui';\nreturn 0 if $answer eq 'n' or $answer eq 'non';\nreturn undef;\n}\n\n...which you'd then call in a construct like this:\n\nmy $response;\nuntil(defined $response) {\nprint $lh->maketext(\"Open the pod bay door (y/n)? \");\n$response = $lh->yorn( getinputfromkeyboardsomehow() );\n}\nif($response) { $podbaydoor->open()         }\nelse          { $podbaydoor->leaveclosed() }\n\nOther data worth storing in a lexicon might be things like filenames for language-targetted\nresources:\n\n...\n\"mainsplashpng\"\n=> \"/styles/enus/mainsplash.png\",\n\"mainsplashimagemap\"\n=> \"/styles/enus/mainsplash.incl\",\n\"generalgraphicspath\"\n=> \"/styles/enus/\",\n\"alertsound\"\n=> \"/styles/enus/heythere.wav\",\n\"forwardicon\"\n=> \"leftarrow.png\",\n\"backwardicon\"\n=> \"rightarrow.png\",\n# In some other languages, left equals\n#  BACKwards, and right is FOREwards.\n...\n\nYou might want to do the same thing for expressing key bindings or the like (since hardwiring\n\"q\" as the binding for the function that quits a screen/menu/program is useful only if your\nlanguage happens to associate \"q\" with \"quit\"!)\n",
            "subsections": []
        },
        "BRACKET NOTATION": {
            "content": "Bracket Notation is a crucial feature of Locale::Maketext. I mean Bracket Notation to provide a\nreplacement for the use of sprintf formatting. Everything you do with Bracket Notation could be\ndone with a sub block, but bracket notation is meant to be much more concise.\n\nBracket Notation is a like a miniature \"template\" system (in the sense of Text::Template, not in\nthe sense of C++ templates), where normal text is passed thru basically as is, but text in\nspecial regions is specially interpreted. In Bracket Notation, you use square brackets\n(\"[...]\"), not curly braces (\"{...}\") to note sections that are specially interpreted.\n\nFor example, here all the areas that are taken literally are underlined with a \"^\", and all the\nin-bracket special regions are underlined with an X:\n\n\"Minimum ([1]) is larger than maximum ([2])!\\n\",\n^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^\n\nWhen that string is compiled from bracket notation into a real Perl sub, it's basically turned\ninto:\n\nsub {\nmy $lh = $[0];\nmy @params = @;\nreturn join '',\n\"Minimum (\",\n...some code here...\n\") is larger than maximum (\",\n...some code here...\n\")!\\n\",\n}\n# to be called by $lh->maketext(KEY, params...)\n\nIn other words, text outside bracket groups is turned into string literals. Text in brackets is\nrather more complex, and currently follows these rules:\n\n*   Bracket groups that are empty, or which consist only of whitespace, are ignored. (Examples:\n\"[]\", \"[ ]\", or a [ and a ] with returns and/or tabs and/or spaces between them.\n\nOtherwise, each group is taken to be a comma-separated group of items, and each item is\ninterpreted as follows:\n\n*   An item that is \"*digits*\" or \"-*digits*\" is interpreted as $[*value*]. I.e., \"1\"\nbecomes with $[1], and \"-3\" is interpreted as $[-3] (in which case @ should have at\nleast three elements in it). Note that $[0] is the language handle, and is typically not\nnamed directly.\n\n*   An item \"*\" is interpreted to mean \"all of @ except $[0]\". I.e., @[1..$#]. Note that\nthis is an empty list in the case of calls like $lh->maketext(*key*) where there are no\nparameters (except $[0], the language handle).\n\n*   Otherwise, each item is interpreted as a string literal.\n\nThe group as a whole is interpreted as follows:\n\n*   If the first item in a bracket group looks like a method name, then that group is\ninterpreted like this:\n\n$lh->thatmethodname(\n...rest of items in this group...\n),\n\n*   If the first item in a bracket group is \"*\", it's taken as shorthand for the so commonly\ncalled \"quant\" method. Similarly, if the first item in a bracket group is \"#\", it's taken to\nbe shorthand for \"numf\".\n\n*   If the first item in a bracket group is the empty-string, or \"*\" or \"*digits*\" or\n\"-*digits*\", then that group is interpreted as just the interpolation of all its items:\n\njoin('',\n...rest of items in this group...\n),\n\nExamples: \"[1]\" and \"[,1]\", which are synonymous; and \"\"[,ID-(,4,-,2,)]\"\", which\ncompiles as \"join \"\", \"ID-(\", $[4], \"-\", $[2], \")\"\".\n\n*   Otherwise this bracket group is invalid. For example, in the group \"[!@#,whatever]\", the\nfirst item \"!@#\" is neither the empty-string, \"*number*\", \"-*number*\", \"*\", nor a valid\nmethod name; and so Locale::Maketext will throw an exception of you try compiling an\nexpression containing this bracket group.\n\nNote, incidentally, that items in each group are comma-separated, not \"/\\s*,\\s*/\"-separated.\nThat is, you might expect that this bracket group:\n\n\"Hoohah [foo, 1 , bar ,baz]!\"\n\nwould compile to this:\n\nsub {\nmy $lh = $[0];\nreturn join '',\n\"Hoohah \",\n$lh->foo( $[1], \"bar\", \"baz\"),\n\"!\",\n}\n\nBut it actually compiles as this:\n\nsub {\nmy $lh = $[0];\nreturn join '',\n\"Hoohah \",\n$lh->foo(\" 1 \", \" bar \", \"baz\"),  # note the <space> in \" bar \"\n\"!\",\n}\n\nIn the notation discussed so far, the characters \"[\" and \"]\" are given special meaning, for\nopening and closing bracket groups, and \",\" has a special meaning inside bracket groups, where\nit separates items in the group. This begs the question of how you'd express a literal \"[\" or\n\"]\" in a Bracket Notation string, and how you'd express a literal comma inside a bracket group.\nFor this purpose I've adopted \"~\" (tilde) as an escape character: \"~[\" means a literal '['\ncharacter anywhere in Bracket Notation (i.e., regardless of whether you're in a bracket group or\nnot), and ditto for \"~]\" meaning a literal ']', and \"~,\" meaning a literal comma. (Altho \",\"\nmeans a literal comma outside of bracket groups -- it's only inside bracket groups that commas\nare special.)\n\nAnd on the off chance you need a literal tilde in a bracket expression, you get it with \"~~\".\n\nCurrently, an unescaped \"~\" before a character other than a bracket or a comma is taken to mean\njust a \"~\" and that character. I.e., \"~X\" means the same as \"~~X\" -- i.e., one literal tilde,\nand then one literal \"X\". However, by using \"~X\", you are assuming that no future version of\nMaketext will use \"~X\" as a magic escape sequence. In practice this is not a great problem,\nsince first off you can just write \"~~X\" and not worry about it; second off, I doubt I'll add\nlots of new magic characters to bracket notation; and third off, you aren't likely to want\nliteral \"~\" characters in your messages anyway, since it's not a character with wide use in\nnatural language text.\n\nBrackets must be balanced -- every openbracket must have one matching closebracket, and vice\nversa. So these are all invalid:\n\n\"I ate [quant,1,rhubarb pie.\"\n\"I ate [quant,1,rhubarb pie[.\"\n\"I ate quant,1,rhubarb pie].\"\n\"I ate quant,1,rhubarb pie[.\"\n\nCurrently, bracket groups do not nest. That is, you cannot say:\n\n\"Foo [bar,baz,[quux,quuux]]\\n\";\n\nIf you need a notation that's that powerful, use normal Perl:\n\n%Lexicon = (\n...\n\"somekey\" => sub {\nmy $lh = $[0];\njoin '',\n\"Foo \",\n$lh->bar('baz', $lh->quux('quuux')),\n\"\\n\",\n},\n...\n);\n\nOr write the \"bar\" method so you don't need to pass it the output from calling quux.\n\nI do not anticipate that you will need (or particularly want) to nest bracket groups, but you\nare welcome to email me with convincing (real-life) arguments to the contrary.\n",
            "subsections": []
        },
        "BRACKET NOTATION SECURITY": {
            "content": "Locale::Maketext does not use any special syntax to differentiate bracket notation methods from\nnormal class or object methods. This design makes it vulnerable to format string attacks\nwhenever it is used to process strings provided by untrusted users.\n\nLocale::Maketext does support denylist and allowlist functionality to limit which methods may be\ncalled as bracket notation methods.\n\nBy default, Locale::Maketext denies all methods in the Locale::Maketext namespace that begin\nwith the '' character, and all methods which include Perl's namespace separator characters.\n\nThe default denylist for Locale::Maketext also prevents use of the following methods in bracket\nnotation:\n\ndenylist\nencoding\nfailwith\nfailurehandlerauto\nfallbacklanguageclasses\nfallbacklanguages\ngethandle\ninit\nlanguagetag\nmaketext\nnew\nallowlist\nwhitelist\nblacklist\n\nThis list can be extended by either deny-listing additional \"known bad\" methods, or\nallow-listing only \"known good\" methods.\n\nTo prevent specific methods from being called in bracket notation, use the denylist() method:\n\nmy $lh = MyProgram::L10N->gethandle();\n$lh->denylist(qw{myinternalmethod myothermethod});\n$lh->maketext('[myinternalmethod]'); # dies\n\nTo limit the allowed bracked notation methods to a specific list, use the allowlist() method:\n\nmy $lh = MyProgram::L10N->gethandle();\n$lh->allowlist('numerate', 'numf');\n$lh->maketext('[1] [numerate, 1,shoe,shoes]', 12); # works\n$lh->maketext('[myinternalmethod]'); # dies\n\nThe denylist() and allowlist() methods extend their internal lists whenever they are called. To\nreset the denylist or allowlist, create a new maketext object.\n\nmy $lh = MyProgram::L10N->gethandle();\n$lh->denylist('numerate');\n$lh->denylist('numf');\n$lh->maketext('[1] [numerate,1,shoe,shoes]', 12); # dies\n\nFor lexicons that use an internal cache, translations which have already been cached in their\ncompiled form are not affected by subsequent changes to the allowlist or denylist settings.\nLexicons that use an external cache will have their cache cleared whenever the allowlist or\ndenylist settings change. The difference between the two types of caching is explained in the\n\"Readonly Lexicons\" section.\n\nMethods disallowed by the denylist cannot be permitted by the allowlist.\n\nNOTE: denylist() is the preferred method name to use instead of the historical and non-inclusive\nmethod blacklist(). blacklist() may be removed in a future release of this package and so it's\nuse should be removed from usage.\n\nNOTE: allowlist() is the preferred method name to use instead of the historical and\nnon-inclusive method whitelist(). whitelist() may be removed in a future release of this package\nand so it's use should be removed from usage.\n",
            "subsections": []
        },
        "AUTO LEXICONS": {
            "content": "If maketext goes to look in an individual %Lexicon for an entry for *key* (where *key* does not\nstart with an underscore), and sees none, but does see an entry of \"AUTO\" => *sometruevalue*,\nthen we actually define $Lexicon{*key*} = *key* right then and there, and then use that value as\nif it had been there all along. This happens before we even look in any superclass %Lexicons!\n\n(This is meant to be somewhat like the AUTOLOAD mechanism in Perl's function call system -- or,\nlooked at another way, like the AutoLoader module.)\n\nI can picture all sorts of circumstances where you just do not want lookup to be able to fail\n(since failing normally means that maketext throws a \"die\", although see the next section for\ngreater control over that). But here's one circumstance where AUTO lexicons are meant to be\n*especially* useful:\n\nAs you're writing an application, you decide as you go what messages you need to emit. Normally\nyou'd go to write this:\n\nif(-e $filename) {\ngoprocessfile($filename)\n} else {\nprint qq{Couldn't find file \"$filename\"!\\n};\n}\n\nbut since you anticipate localizing this, you write:\n\nuse ThisProject::I18N;\nmy $lh = ThisProject::I18N->gethandle();\n# For the moment, assume that things are set up so\n# that we load class ThisProject::I18N::en\n# and that that's the class that $lh belongs to.\n...\nif(-e $filename) {\ngoprocessfile($filename)\n} else {\nprint $lh->maketext(\nqq{Couldn't find file \"[1]\"!\\n}, $filename\n);\n}\n\nNow, right after you've just written the above lines, you'd normally have to go open the file\nThisProject/I18N/en.pm, and immediately add an entry:\n\n\"Couldn't find file \\\"[1]\\\"!\\n\"\n=> \"Couldn't find file \\\"[1]\\\"!\\n\",\n\nBut I consider that somewhat of a distraction from the work of getting the main code working --\nto say nothing of the fact that I often have to play with the program a few times before I can\ndecide exactly what wording I want in the messages (which in this case would require me to go\nchanging three lines of code: the call to maketext with that key, and then the two lines in\nThisProject/I18N/en.pm).\n\nHowever, if you set \"AUTO => 1\" in the %Lexicon in, ThisProject/I18N/en.pm (assuming that\nEnglish (en) is the language that all your programmers will be using for this project's internal\nmessage keys), then you don't ever have to go adding lines like this\n\n\"Couldn't find file \\\"[1]\\\"!\\n\"\n=> \"Couldn't find file \\\"[1]\\\"!\\n\",\n\nto ThisProject/I18N/en.pm, because if AUTO is true there, then just looking for an entry with\nthe key \"Couldn't find file \\\"[1]\\\"!\\n\" in that lexicon will cause it to be added, with that\nvalue!\n\nNote that the reason that keys that start with \"\" are immune to AUTO isn't anything generally\nmagical about the underscore character -- I just wanted a way to have most lexicon keys be\nautoable, except for possibly a few, and I arbitrarily decided to use a leading underscore as a\nsignal to distinguish those few.\n",
            "subsections": []
        },
        "READONLY LEXICONS": {
            "content": "If your lexicon is a tied hash the simple act of caching the compiled value can be fatal.\n\nFor example a GDBMFile GDBMREADER tied hash will die with something like:\n\ngdbm store returned -1, errno 2, key \"...\" at ...\n\nAll you need to do is turn on caching outside of the lexicon hash itself like so:\n\nsub init {\nmy ($lh) = @;\n...\n$lh->{'useexternallexcache'} = 1;\n...\n}\n\nAnd then instead of storing the compiled value in the lexicon hash it will store it in\n$lh->{'externallexcache'}\n",
            "subsections": []
        },
        "CONTROLLING LOOKUP FAILURE": {
            "content": "If you call $lh->maketext(*key*, ...parameters...), and there's no entry *key* in $lh's class's\n%Lexicon, nor in the superclass %Lexicon hash, *and* if we can't auto-make *key* (because either\nit starts with a \"\", or because none of its lexicons have \"AUTO => 1,\"), then we have failed\nto find a normal way to maketext *key*. What then happens in these failure conditions, depends\non the $lh object's \"fail\" attribute.\n\nIf the language handle has no \"fail\" attribute, maketext will simply throw an exception (i.e.,\nit calls \"die\", mentioning the *key* whose lookup failed, and naming the line number where the\ncalling $lh->maketext(*key*,...) was.\n\nIf the language handle has a \"fail\" attribute whose value is a coderef, then\n$lh->maketext(*key*,...params...) gives up and calls:\n\nreturn $thatsubref->($lh, $key, @params);\n\nOtherwise, the \"fail\" attribute's value should be a string denoting a method name, so that\n$lh->maketext(*key*,...params...) can give up with:\n\nreturn $lh->$thatmethodname($phrase, @params);\n\nThe \"fail\" attribute can be accessed with the \"failwith\" method:\n\n# Set to a coderef:\n$lh->failwith( \\&failurehandler );\n\n# Set to a method name:\n$lh->failwith( 'failuremethod' );\n\n# Set to nothing (i.e., so failure throws a plain exception)\n$lh->failwith( undef );\n\n# Get the current value\n$handler = $lh->failwith();\n\nNow, as to what you may want to do with these handlers: Maybe you'd want to log what key failed\nfor what class, and then die. Maybe you don't like \"die\" and instead you want to send the error\nmessage to STDOUT (or wherever) and then merely exit().\n\nOr maybe you don't want to \"die\" at all! Maybe you could use a handler like this:\n\n# Make all lookups fall back onto an English value,\n#  but only after we log it for later fingerpointing.\nmy $lhbackup = ThisProject->gethandle('en');\nopen(LEXFAILLOG, \">>wherever/lex.log\") || die \"GNAARGH $!\";\nsub lexfail {\nmy($failinglh, $key, $params) = @;\nprint LEXFAILLOG scalar(localtime), \"\\t\",\nref($failinglh), \"\\t\", $key, \"\\n\";\nreturn $lhbackup->maketext($key,@params);\n}\n\nSome users have expressed that they think this whole mechanism of having a \"fail\" attribute at\nall, seems a rather pointless complication. But I want Locale::Maketext to be usable for\nsoftware projects of *any* scale and type; and different software projects have different ideas\nof what the right thing is to do in failure conditions. I could simply say that failure always\nthrows an exception, and that if you want to be careful, you'll just have to wrap every call to\n$lh->maketext in an eval { }. However, I want programmers to reserve the right (via the \"fail\"\nattribute) to treat lookup failure as something other than an exception of the same level of\nseverity as a config file being unreadable, or some essential resource being inaccessible.\n\nOne possibly useful value for the \"fail\" attribute is the method name \"failurehandlerauto\".\nThis is a method defined in the class Locale::Maketext itself. You set it with:\n\n$lh->failwith('failurehandlerauto');\n\nThen when you call $lh->maketext(*key*, ...parameters...) and there's no *key* in any of those\nlexicons, maketext gives up with\n\nreturn $lh->failurehandlerauto($key, @params);\n\nBut failurehandlerauto, instead of dying or anything, compiles $key, caching it in\n\n$lh->{'failurelex'}{$key} = $compiled\n\nand then calls the compiled value, and returns that. (I.e., if $key looks like bracket notation,\n$compiled is a sub, and we return &{$compiled}(@params); but if $key is just a plain string, we\njust return that.)\n\nThe effect of using \"failureautohandler\" is like an AUTO lexicon, except that it 1) compiles\n$key even if it starts with \"\", and 2) you have a record in the new hashref\n$lh->{'failurelex'} of all the keys that have failed for this object. This should avoid your\nprogram dying -- as long as your keys aren't actually invalid as bracket code, and as long as\nthey don't try calling methods that don't exist.\n\n\"failureautohandler\" may not be exactly what you want, but I hope it at least shows you that\nmaketext failure can be mitigated in any number of very flexible ways. If you can formalize\nexactly what you want, you should be able to express that as a failure handler. You can even\nmake it default for every object of a given class, by setting it in that class's init:\n\nsub init {\nmy $lh = $[0];  # a newborn handle\n$lh->SUPER::init();\n$lh->failwith('mycleverfailurehandler');\nreturn;\n}\nsub mycleverfailurehandler {\n...you clever things here...\n}\n",
            "subsections": []
        },
        "HOW TO USE MAKETEXT": {
            "content": "Here is a brief checklist on how to use Maketext to localize applications:\n\n*   Decide what system you'll use for lexicon keys. If you insist, you can use opaque IDs (if\nyou're nostalgic for \"catgets\"), but I have better suggestions in the section \"Entries in\nEach Lexicon\", above. Assuming you opt for meaningful keys that double as values (like\n\"Minimum ([1]) is larger than maximum ([2])!\\n\"), you'll have to settle on what language\nthose should be in. For the sake of argument, I'll call this English, specifically American\nEnglish, \"en-US\".\n\n*   Create a class for your localization project. This is the name of the class that you'll use\nin the idiom:\n\nuse Projname::L10N;\nmy $lh = Projname::L10N->gethandle(...) || die \"Language?\";\n\nAssuming you call your class Projname::L10N, create a class consisting minimally of:\n\npackage Projname::L10N;\nuse base qw(Locale::Maketext);\n...any methods you might want all your languages to share...\n\n# And, assuming you want the base class to be an AUTO lexicon,\n# as is discussed a few sections up:\n\n1;\n\n*   Create a class for the language your internal keys are in. Name the class after the\nlanguage-tag for that language, in lowercase, with dashes changed to underscores. Assuming\nyour project's first language is US English, you should call this Projname::L10N::enus. It\nshould consist minimally of:\n\npackage Projname::L10N::enus;\nuse base qw(Projname::L10N);\n%Lexicon = (\n'AUTO' => 1,\n);\n1;\n\n(For the rest of this section, I'll assume that this \"first language class\" of\nProjname::L10N::enus has AUTO lexicon.)\n\n*   Go and write your program. Everywhere in your program where you would say:\n\nprint \"Foobar $thing stuff\\n\";\n\ninstead do it thru maketext, using no variable interpolation in the key:\n\nprint $lh->maketext(\"Foobar [1] stuff\\n\", $thing);\n\nIf you get tired of constantly saying \"print $lh->maketext\", consider making a functional\nwrapper for it, like so:\n\nuse Projname::L10N;\nour $lh;\n$lh = Projname::L10N->gethandle(...) || die \"Language?\";\nsub pmt (@) { print( $lh->maketext(@)) }\n# \"pmt\" is short for \"Print MakeText\"\n$Carp::Verbose = 1;\n# so if maketext fails, we see made the call to pmt\n\nBesides whole phrases meant for output, anything language-dependent should be put into the\nclass Projname::L10N::enus, whether as methods, or as lexicon entries -- this is discussed\nin the section \"Entries in Each Lexicon\", above.\n\n*   Once the program is otherwise done, and once its localization for the first language works\nright (via the data and methods in Projname::L10N::enus), you can get together the data for\ntranslation. If your first language lexicon isn't an AUTO lexicon, then you already have\nall the messages explicitly in the lexicon (or else you'd be getting exceptions thrown when\nyou call $lh->maketext to get messages that aren't in there). But if you were (advisedly)\nlazy and are using an AUTO lexicon, then you've got to make a list of all the phrases that\nyou've so far been letting AUTO generate for you. There are very many ways to assemble such\na list. The most straightforward is to simply grep the source for every occurrence of\n\"maketext\" (or calls to wrappers around it, like the above \"pmt\" function), and to log the\nfollowing phrase.\n\n*   You may at this point want to consider whether your base class (Projname::L10N), from which\nall lexicons inherit from (Projname::L10N::en, Projname::L10N::es, etc.), should be an AUTO\nlexicon. It may be true that in theory, all needed messages will be in each language class;\nbut in the presumably unlikely or \"impossible\" case of lookup failure, you should consider\nwhether your program should throw an exception, emit text in English (or whatever your\nproject's first language is), or some more complex solution as described in the section\n\"Controlling Lookup Failure\", above.\n\n*   Submit all messages/phrases/etc. to translators.\n\n(You may, in fact, want to start with localizing to *one* other language at first, if you're\nnot sure that you've properly abstracted the language-dependent parts of your code.)\n\nTranslators may request clarification of the situation in which a particular phrase is\nfound. For example, in English we are entirely happy saying \"*n* files found\", regardless of\nwhether we mean \"I looked for files, and found *n* of them\" or the rather distinct situation\nof \"I looked for something else (like lines in files), and along the way I saw *n* files.\"\nThis may involve rethinking things that you thought quite clear: should \"Edit\" on a toolbar\nbe a noun (\"editing\") or a verb (\"to edit\")? Is there already a conventionalized way to\nexpress that menu option, separate from the target language's normal word for \"to edit\"?\n\nIn all cases where the very common phenomenon of quantification (saying \"*N* files\", for any\nvalue of N) is involved, each translator should make clear what dependencies the number\ncauses in the sentence. In many cases, dependency is limited to words adjacent to the\nnumber, in places where you might expect them (\"I found the-?PLURAL *N* empty-?PLURAL\ndirectory-?PLURAL\"), but in some cases there are unexpected dependencies (\"I found-?PLURAL\n...\"!) as well as long-distance dependencies \"The *N* directory-?PLURAL could not be\ndeleted-?PLURAL\"!).\n\nRemind the translators to consider the case where N is 0: \"0 files found\" isn't exactly\nnatural-sounding in any language, but it may be unacceptable in many -- or it may condition\nspecial kinds of agreement (similar to English \"I didN'T find ANY files\").\n\nRemember to ask your translators about numeral formatting in their language, so that you can\noverride the \"numf\" method as appropriate. Typical variables in number formatting are: what\nto use as a decimal point (comma? period?); what to use as a thousands separator (space?\nnonbreaking space? comma? period? small middot? prime? apostrophe?); and even whether the\nso-called \"thousands separator\" is actually for every third digit -- I've heard reports of\ntwo hundred thousand being expressible as \"2,00,000\" for some Indian (Subcontinental)\nlanguages, besides the less surprising \"200 000\", \"200.000\", \"200,000\", and \"200'000\". Also,\nusing a set of numeral glyphs other than the usual ASCII \"0\"-\"9\" might be appreciated, as\nvia \"tr/0-9/\\x{0966}-\\x{096F}/\" for getting digits in Devanagari script (for Hindi, Konkani,\nothers).\n\nThe basic \"quant\" method that Locale::Maketext provides should be good for many languages.\nFor some languages, it might be useful to modify it (or its constituent \"numerate\" method)\nto take a plural form in the two-argument call to \"quant\" (as in \"[quant,1,files]\") if it's\nall-around easier to infer the singular form from the plural, than to infer the plural form\nfrom the singular.\n\nBut for other languages (as is discussed at length in Locale::Maketext::TPJ13), simple\n\"quant\"/\"numf\" is not enough. For the particularly problematic Slavic languages, what you\nmay need is a method which you provide with the number, the citation form of the noun to\nquantify, and the case and gender that the sentence's syntax projects onto that noun slot.\nThe method would then be responsible for determining what grammatical number that numeral\nprojects onto its noun phrase, and what case and gender it may override the normal case and\ngender with; and then it would look up the noun in a lexicon providing all needed inflected\nforms.\n\n*   You may also wish to discuss with the translators the question of how to relate different\nsubforms of the same language tag, considering how this reacts with \"gethandle\"'s treatment\nof these. For example, if a user accepts interfaces in \"en, fr\", and you have interfaces\navailable in \"en-US\" and \"fr\", what should they get? You may wish to resolve this by\nestablishing that \"en\" and \"en-US\" are effectively synonymous, by having one class\nzero-derive from the other.\n\nFor some languages this issue may never come up (Danish is rarely expressed as \"da-DK\", but\ninstead is just \"da\"). And for other languages, the whole concept of a \"generic\" form may\nverge on being uselessly vague, particularly for interfaces involving voice media in forms\nof Arabic or Chinese.\n\n*   Once you've localized your program/site/etc. for all desired languages, be sure to show the\nresult (whether live, or via screenshots) to the translators. Once they approve, make every\neffort to have it then checked by at least one other speaker of that language. This holds\ntrue even when (or especially when) the translation is done by one of your own programmers.\nSome kinds of systems may be harder to find testers for than others, depending on the amount\nof domain-specific jargon and concepts involved -- it's easier to find people who can tell\nyou whether they approve of your translation for \"delete this message\" in an email-via-Web\ninterface, than to find people who can give you an informed opinion on your translation for\n\"attribute value\" in an XML query tool's interface.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "I recommend reading all of these:\n\nLocale::Maketext::TPJ13 -- my *The Perl Journal* article about Maketext. It explains many\nimportant concepts underlying Locale::Maketext's design, and some insight into why Maketext is\nbetter than the plain old approach of having message catalogs that are just databases of sprintf\nformats.\n\nFile::Findgrep is a sample application/module that uses Locale::Maketext to localize its\nmessages. For a larger internationalized system, see also Apache::MP3.\n\nI18N::LangTags.\n\nWin32::Locale.\n\nRFC 3066, *Tags for the Identification of Languages*, as at\n<http://sunsite.dk/RFC/rfc/rfc3066.html>\n\nRFC 2277, *IETF Policy on Character Sets and Languages* is at\n<http://sunsite.dk/RFC/rfc/rfc2277.html> -- much of it is just things of interest to protocol\ndesigners, but it explains some basic concepts, like the distinction between locales and\nlanguage-tags.\n\nThe manual for GNU \"gettext\". The gettext dist is available in\n\"<ftp://prep.ai.mit.edu/pub/gnu/>\" -- get a recent gettext tarball and look in its \"doc/\"\ndirectory, there's an easily browsable HTML version in there. The gettext documentation asks\nlots of questions worth thinking about, even if some of their answers are sometimes wonky,\nparticularly where they start talking about pluralization.\n\nThe Locale/Maketext.pm source. Observe that the module is much shorter than its documentation!\n",
            "subsections": []
        },
        "COPYRIGHT AND DISCLAIMER": {
            "content": "Copyright (c) 1999-2004 Sean M. Burke. All rights reserved.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nThis program is distributed in the hope that it will be useful, but without any warranty;\nwithout even the implied warranty of merchantability or fitness for a particular purpose.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Sean M. Burke \"sburke@cpan.org\"\n",
            "subsections": []
        }
    },
    "summary": "Locale::Maketext - framework for localization",
    "flags": [],
    "examples": [],
    "see_also": []
}