Documentation 4.0

Note: I will refer to PO content data to refer any source of data containing a string following this description.

Parsing

There are three methods to parse formatted PO content:

parseFile( $filepath )
Parses a po file

parseString( $string )
Parses a compliant po string. This is useful when you want to use your own method to read a po file instead of the built-in.

parse( $handler )
Parses data using a $handler. This $handler must be an object of a class implementing the interface InterfaceHandler. This allows theoretically to parse form any source containing a compliant po formatted data (for example you could write your own database handler).

Any of these methods return an array of entries with the following structure:

• msgid: String Array. Entry identifier.
• msgstr: String Array. Translated string.
• reference: String Array. Source code filepaths where this message is found.
• msgctxt: String. Disambiguating context.
• tcomment: String Array. Translator comments.
• ccomment: String Array. Source code comments linked to the message.
• obsolete: Bool (1/0). Marks the entry as obsolete.
• fuzzy: Bool (1/0). Marks the entry as a fuzzy translation.
• flags: Array. List of entry flags
• previous: Array. Contains previous unstranslated strings in a sub array with msgid and msgstr.

This array is indexed using the msgid. Please note that headers are not included in this returned array.
The class stores a copy of this parsed array.
Any errors found in the parser process will throw an Exception.

Multiline entries

Some entries can have multi-lined msgid, in this case the key used to index that entry will be implode('<##EOL##>', <msgid>). Example:

A po file containing:

msgid ""
"Atención, para finalizar el proceso debes iniciar sesión con tu usuario "
"te autentifiques te redirigiremos al paso final."
msgstr ""
"Atenció, per finalitzar el procés has de iniciar sessió amb el teu usuari "
"t'autentifiquis finalitzarem el procés."

Will be indexed as (note the '<##EOL##>' that join the multilined msgid):

array(
    "<##EOL##>Atención, para finalizar el proceso debes iniciar sesión con tu usuario <##EOL##>te autentifiques te redirigiremos al paso final." => array(
         'msgid'=> array(
             "",
             "Atención, para finalizar el proceso debes iniciar sesión con tu usuario ",
             "te autentifiques te redirigiremos al paso final."
         ),
         'msgstr'=> array(
              "Atenció, per finalitzar el procés has de iniciar sessió amb el teu usuari ",
              "t'autentifiquis finalitzarem el procés."
         )
    )
)

###Context entries It's possible a PO data contains entries with a context specifier.

The context serves to disambiguate messages with the same untranslated-string. It is possible to have several entries with the same untranslated-string in a PO file, provided that they each have a different context. Note that an empty context string and an absent msgctxt line do not mean the same thing.

As PoParser indexes entries by its msgid, when detecting a context this is prepended to this index to avoid overwriting previous elements in the array. Example:

msgctxt "File"
msgid "Open"
msgstr "Abrir"

msgctxt "Issue"
msgid "Open"
msgstr "Nuevo"

This will be converted to:

array(
    "File<##EOC##>Open" => array(
         'msgid'=> array("Open"),
         'msgctxt'=>'File',
         'msgstr'=> array("Abrir")
    ),
    "Issue<##EOC##>Open" => array(
         'msgid'=> array("Open"),
         'msgctxt'=>'Issue',
         'msgstr'=> array("Nuevo")
    ),
)

getHeaders()
Once data has been parsed, you can call this method to get the header section of the PO Content data. You will get a simple string array.

entries() Returns entries previously parsed (and modified with updateEntry()).

Modifying

Once a PO Content Data has been parsed, you can modify it with following methods:

setHeaders($newHeaders)
This allows you to set all headers at once, replacing those already parsed.
You're expected to pass headers like this:

$newHeaders = array(
   '"Project-Id-Version: \n"',
   '"Report-Msgid-Bugs-To: \n"',
   '"POT-Creation-Date: \n"',
   '"PO-Revision-Date: \n"',
   '"Last-Translator: none\n"',
   '"Language-Team: \n"',
   '"MIME-Version: 1.0\n"',
   '"Content-Type: text/plain; charset=UTF-8\n"',
  );

updateEntry($msgid, $msgstr=null, $tcomment=array(), $ccomment=array(), $flags=array(), $createNew=false)
This method allows you to modify an existing entry, specifying new value for msgstr ($msgstr), translator comments ($tcomment), code comments ($ccomment) and set any flags ($flags).

Parameters:

• msgid String. Used to refer to the entry you want to modify. When updating an entry which its msgid is defined as multi-line, You must join each line by using an ',' as glue.
• msgstrString/Array. New translation. When passing an array, output will be stored as multi-line.
• tcomment String/Array. New translator comment. When passing an array, output will be stored as multi-line.
• ccomment String/Array. New code comment. When passing an array, output will be stored as multi-line.
• flags Array. An array containing each flags desired to be placed. Example: array('fuzzy','php-format')
• createNew Bool. Controls if a new entry should be created when msgid is not found in internal list. Default false.

Writing

PoParser allows writing back to a PO file.

writeFile($filepath) Just as it says, pass it a filepath and it will save the internal entries previously parsed and modified into a file.
Throws an Exception if an error occurs.

compile() This method compiles all entries into a valid PO format string so you can do it with it what you need.
Returns String.