{ "content": [ { "type": "text", "text": "# Locale::Maketext::Extract (perldoc)\n\n## NAME\n\nLocale::Maketext::Extract - Extract translatable strings from source\n\n## SYNOPSIS\n\nmy $Ext = Locale::Maketext::Extract->new;\n$Ext->readpo('messages.po');\n$Ext->extractfile($) for <*.pl>;\n# Set $entriesareingettextformat if the .pl files above use\n# loc('%1') instead of loc('[1]')\n$Ext->compile($entriesareingettextformat);\n$Ext->writepo('messages.po');\n-----------------------------------\n### Specifying parser plugins ###\nmy $Ext = Locale::Maketext::Extract->new(\n# Specify which parser plugins to use\nplugins => {\n# Use Perl parser, process files with extension .pl .pm .cgi\nperl => [],\n# Use YAML parser, process all files\nyaml => ['*'],\n# Use TT2 parser, process files with extension .tt2 .tt .html\n# or which match the regex\ntt2 => [\n'tt2',\n'tt',\n'html',\nqr/\\.tt2?\\./\n],\n# Use My::Module as a parser for all files\n'My::Module' => ['*'],\n},\n# Warn if a parser can't process a file or problems loading a plugin\nwarnings => 1,\n# List processed files\nverbose => 1,\n);\n\n## DESCRIPTION\n\nThis module can extract translatable strings from files, and write them back to PO files. It can\nalso parse existing PO files and merge their contents with newly extracted strings.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS** (9 subsections)\n- **ACKNOWLEDGMENTS**\n- **SEE ALSO**\n- **AUTHORS**\n- **COPYRIGHT**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Locale::Maketext::Extract", "section": "", "mode": "perldoc", "summary": "Locale::Maketext::Extract - Extract translatable strings from source", "synopsis": "my $Ext = Locale::Maketext::Extract->new;\n$Ext->readpo('messages.po');\n$Ext->extractfile($) for <*.pl>;\n# Set $entriesareingettextformat if the .pl files above use\n# loc('%1') instead of loc('[1]')\n$Ext->compile($entriesareingettextformat);\n$Ext->writepo('messages.po');\n-----------------------------------\n### Specifying parser plugins ###\nmy $Ext = Locale::Maketext::Extract->new(\n# Specify which parser plugins to use\nplugins => {\n# Use Perl parser, process files with extension .pl .pm .cgi\nperl => [],\n# Use YAML parser, process all files\nyaml => ['*'],\n# Use TT2 parser, process files with extension .tt2 .tt .html\n# or which match the regex\ntt2 => [\n'tt2',\n'tt',\n'html',\nqr/\\.tt2?\\./\n],\n# Use My::Module as a parser for all files\n'My::Module' => ['*'],\n},\n# Warn if a parser can't process a file or problems loading a plugin\nwarnings => 1,\n# List processed files\nverbose => 1,\n);", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 47, "subsections": [] }, { "name": "DESCRIPTION", "lines": 56, "subsections": [] }, { "name": "METHODS", "lines": 1, "subsections": [ { "name": "Constructor", "lines": 10 }, { "name": "Plugins", "lines": 62 }, { "name": "Warnings", "lines": 12 }, { "name": "Verbose", "lines": 11 }, { "name": "Accessors", "lines": 10 }, { "name": "Extraction", "lines": 3 }, { "name": "Compilation", "lines": 13 }, { "name": "Lexicon accessors", "lines": 4 }, { "name": "Internal utilities", "lines": 6 } ] }, { "name": "ACKNOWLEDGMENTS", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHORS", "lines": 4, "subsections": [] }, { "name": "COPYRIGHT", "lines": 20, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "Locale::Maketext::Extract - Extract translatable strings from source\n", "subsections": [] }, "VERSION": { "content": "version 1.00\n", "subsections": [] }, "SYNOPSIS": { "content": "my $Ext = Locale::Maketext::Extract->new;\n$Ext->readpo('messages.po');\n$Ext->extractfile($) for <*.pl>;\n\n# Set $entriesareingettextformat if the .pl files above use\n# loc('%1') instead of loc('[1]')\n$Ext->compile($entriesareingettextformat);\n\n$Ext->writepo('messages.po');\n\n-----------------------------------\n\n### Specifying parser plugins ###\n\nmy $Ext = Locale::Maketext::Extract->new(\n\n# Specify which parser plugins to use\nplugins => {\n\n# Use Perl parser, process files with extension .pl .pm .cgi\nperl => [],\n\n# Use YAML parser, process all files\nyaml => ['*'],\n\n# Use TT2 parser, process files with extension .tt2 .tt .html\n# or which match the regex\ntt2 => [\n'tt2',\n'tt',\n'html',\nqr/\\.tt2?\\./\n],\n\n# Use My::Module as a parser for all files\n'My::Module' => ['*'],\n\n},\n\n# Warn if a parser can't process a file or problems loading a plugin\nwarnings => 1,\n\n# List processed files\nverbose => 1,\n\n);\n", "subsections": [] }, "DESCRIPTION": { "content": "This module can extract translatable strings from files, and write them back to PO files. It can\nalso parse existing PO files and merge their contents with newly extracted strings.\n\nA command-line utility, xgettext.pl, is installed with this module as well.\n\nThe format parsers are loaded as plugins, so it is possible to define your own parsers.\n\nFollowing formats of input files are supported:\n\nPerl source files (plugin: perl)\nValid localization function names are: \"translate\", \"maketext\", \"gettext\", \"l\", \"loc\", \"x\",\n\"\" and \"\".\n\nFor a slightly more accurate, but much slower Perl parser, you can use the PPI plugin. This\ndoes not have a short name (like \"perl\"), but must be specified in full.\n\nHTML::Mason (Mason 1) and Mason (Mason 2) (plugin: mason)\nHTML::Mason (aka Mason 1) Strings inside <&|/l>... and <&|/loc>... are extracted.\n\nMason (aka Mason 2) Strings inside <% $.floc { %>... or <% $.fl { %>... or <%\n$self->floc { %>... or <% $self->fl { %>... are extracted.\n\nTemplate Toolkit (plugin: tt2)\nValid forms are:\n\n[% | l(arg1,argn) %]string[% END %]\n[% 'string' | l(arg1,argn) %]\n[% l('string',arg1,argn) %]\n\nFILTER and | are interchangeable\nl and loc are interchangeable\nargs are optional\n\nText::Template (plugin: text)\nSentences between \"STARTxxx\" and \"ENDxxx\" are extracted individually.\n\nYAML (plugin: yaml)\nValid forms are \"string\" or 'string', eg:\n\ntitle: \"My title\"\ndesc: 'My \"quoted\" string'\n\nQuotes do not have to be escaped, so you could also do:\n\ndesc: \"My \"quoted\" string\"\n\nHTML::FormFu (plugin: formfu)\nHTML::FormFu uses a config-file to generate forms, with built in support for localizing\nerrors, labels etc.\n\nWe extract the text after \"loc: \": contentloc: this is the string messageloc: ['Max\nstring length: [1]', 10]\n\nGeneric Template (plugin: generic)\nStrings inside {{...}} are extracted.\n", "subsections": [] }, "METHODS": { "content": "", "subsections": [ { "name": "Constructor", "content": "new()\n\nnew(\nplugins => {...},\nwarnings => 1 | 0,\nverbose => 0 | 1 | 2 | 3,\n)\n\nSee \"Plugins\", \"Warnings\" and \"Verbose\" for details\n" }, { "name": "Plugins", "content": "$ext->plugins({...});\n\nLocale::Maketext::Extract uses plugins (see below for the list) to parse different formats.\n\nEach plugin can also specify which file types it can parse.\n\n# use only the YAML plugin\n# only parse files with the default extension list defined in the plugin\n# ie .yaml .yml .conf\n\n$ext->plugins({\nyaml => [],\n})\n\n\n# use only the Perl plugin\n# parse all file types\n\n$ext->plugins({\nperl => '*'\n})\n\n$ext->plugins({\ntt2 => [\n'tt', # matches base filename against /\\.tt$/\nqr/\\.tt2?\\./, # matches base filename against regex\n\\&myfilter, # codref called\n]\n})\n\nsub myfilter {\nmy ($basefilename,$pathtofile) = @;\n\nreturn 1 | 0;\n}\n\n# Specify your own parser\n# only parse files with the default extension list defined in the plugin\n\n$ext->plugins({\n'My::Extract::Parser' => []\n})\n\nBy default, if no plugins are specified, it first tries to determine which plugins are intended\nspecifically for the file type and uses them. If no such plugins are found, it then uses all of\nthe builtin plugins, overriding the file types specified in each.\n\nAvailable plugins\n\"perl\" : Locale::Maketext::Extract::Plugin::Perl\nFor a slightly more accurate but much slower Perl parser, you can use the PPI plugin. This\ndoes not have a short name, but must be specified in full, ie:\nLocale::Maketext::Extract::Plugin::PPI\n\n\"tt2\" : Locale::Maketext::Extract::Plugin::TT2\n\"yaml\" : Locale::Maketext::Extract::Plugin::YAML\n\"formfu\" : Locale::Maketext::Extract::Plugin::FormFu\n\"mason\" : Locale::Maketext::Extract::Plugin::Mason\n\"text\" : Locale::Maketext::Extract::Plugin::TextTemplate\n\"generic\" : Locale::Maketext::Extract::Plugin::Generic\n\nAlso, see Locale::Maketext::Extract::Plugin::Base for details of how to write your own plugin.\n" }, { "name": "Warnings", "content": "Because the YAML and TT2 plugins use proper parsers, rather than just regexes, if a source file\nis not valid and it is unable to parse the file, then the parser will throw an error and abort\nparsing.\n\nThe next enabled plugin will be tried.\n\nBy default, you will not see these errors. If you would like to see them, then enable warnings\nvia new(). All parse errors will be printed to STDERR.\n\nAlso, if developing your own plugin, turn on warnings to see any errors that result from loading\nyour plugin.\n" }, { "name": "Verbose", "content": "If you would like to see which files have been processed, which plugins were used, and which\nstrings were extracted, then enable \"verbose\". If no acceptable plugin was found, or no strings\nwere extracted, then the file is not listed:\n\n$ext = Locale::Extract->new( verbose => 1 | 2 | 3);\n\nOR\nxgettext.pl ... -v # files reported\nxgettext.pl ... -v -v # files and plugins reported\nxgettext.pl ... -v -v -v # files, plugins and strings reported\n" }, { "name": "Accessors", "content": "header, setheader\nlexicon, setlexicon, msgstr, setmsgstr\nentries, setentries, entry, addentry, delentry\ncompiledentries, setcompiledentries, compiledentry,\naddcompiledentry, delcompiledentry\nclear\n\nPO File manipulation\nmethod readpo ($file)\nmethod writepo ($file, $addformatmarker?)" }, { "name": "Extraction", "content": "extract\nextractfile\n" }, { "name": "Compilation", "content": "compile($entriesareingettextstyle?)\nMerges the \"entries\" into \"compiledentries\".\n\nIf $entriesareingettextstyle is true, the previously extracted entries are assumed to be in\nthe Gettext style (e.g. %1).\n\nOtherwise they are assumed to be in Maketext style (e.g. \"[1]\") and are converted into Gettext\nstyle before merging into \"compiledentries\".\n\nThe \"entries\" are *not* cleared after each compilation; use \"-\"setentries()> to clear them if\nyou need to extract from sources with varying styles.\n\nnormalizespace" }, { "name": "Lexicon accessors", "content": "msgids, hasmsgid,\nmsgstr, setmsgstr\nmsgpositions, msgvariables, msgformat, msgout\n" }, { "name": "Internal utilities", "content": "defaultheader\nmaketexttogettext\nescape\nformat\npluginsspecificallyforfile\n" } ] }, "ACKNOWLEDGMENTS": { "content": "Thanks to Jesse Vincent for contributing to an early version of this module.\n\nAlso to Alain Barbet, who effectively re-wrote the source parser with a flex-like algorithm.\n", "subsections": [] }, "SEE ALSO": { "content": "xgettext.pl, Locale::Maketext, Locale::Maketext::Lexicon\n", "subsections": [] }, "AUTHORS": { "content": "* Clinton Gormley \n\n* Audrey Tang \n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2003-2013 by Audrey Tang .\n\nThis software is released under the MIT license cited below.\n\nThe \"MIT\" License\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software\nand associated documentation files (the \"Software\"), to deal in the Software without\nrestriction, including without limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or\nsubstantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING\nBUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,\nDAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is Copyright (c) 2014 by Audrey Tang.\n\nThis is free software, licensed under:\n\nThe MIT (X11) License\n", "subsections": [] } } } }