Merge pull request #283 from jonasraoni/feature/master/282-add-strict-po-loader

#282 Add strict po loader

Author: oscarotero

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 Previous releases are documented in [github releases](https://github.com/oscarotero/Gettext/releases)
 
+## [5.7.0] - 2021-07-27
+### Added
+- StrictPoLoader, a stricter PO loader more aligned with the syntax of the GNU gettext tooling [#282].
+- Previous attributes (msgctxt, msgid, msgid_plural) to the Translation class and the PO generator [#282].
+### Changed
+- Minor performance improvements to the Translations class [#282].
+
 ## [5.6.1] - 2021-12-04
 ### Fixed
 - PHP 8.1 support [#278].
@@ -112,7 +119,9 @@ Previous releases are documented in [github releases](https://github.com/oscarot
 [#265]: https://github.com/php-gettext/Gettext/issues/265
 [#276]: https://github.com/php-gettext/Gettext/issues/276
 [#278]: https://github.com/php-gettext/Gettext/issues/278
+[#282]: https://github.com/php-gettext/Gettext/issues/282
 
+[5.7.0]: https://github.com/php-gettext/Gettext/compare/v5.6.1...v5.7.0
 [5.6.1]: https://github.com/php-gettext/Gettext/compare/v5.6.0...v5.6.1
 [5.6.0]: https://github.com/php-gettext/Gettext/compare/v5.5.4...v5.6.0
 [5.5.4]: https://github.com/php-gettext/Gettext/compare/v5.5.3...v5.5.4

README.md

@@ -94,7 +94,7 @@ $translations->setDomain('my-blog');
 
 ## Loaders
 
-The loaders allows to get gettext values from any format. For example, to load a .po file:
+The loaders allow to get gettext values from multiple formats. For example, to load a .po file:
 
 ```php
 use Gettext\Loader\PoLoader;
@@ -109,10 +109,39 @@ $string = file_get_contents('locales2/en.po');
 $translations = $loader->loadString($string);
 ```
 
+As of version 5.7.0, a `StrictPoLoader` has been included, with a parser more aligned to the GNU gettext tooling with the same expectations and failures (see the tests for more details).
+- It will fail with an exception when there's anything wrong with the syntax, and display the reason together with the line/byte where it happened.
+- It might also emit useful warnings, e.g. when there are more/less plural translations than needed, missing translation header, dangling comments not associated with any translation, etc.
+- Due to its strictness and speed (about 50% slower than the `PoLoader`), it might be interesting to be used as a kind of `.po` linter in a build system.
+- It also implements the previous translation comment (e.g. `#| msgid "previous"`) and extra escapes (16-bit unicode `\u`, 32-bit unicode `\U`, hexadecimal `\xFF` and octal `\77`).
+
+The usage is basically the same as the `PoLoader`:
+
+```php
+use Gettext\Loader\StrictPoLoader;
+
+$loader = new StrictPoLoader();
+
+//From a file
+$translations = $loader->loadFile('locales/en.po');
+
+//From a string
+$string = file_get_contents('locales2/en.po');
+$translations = $loader->loadString($string);
+
+//Display error messages using "at line X column Y" instead of "at byte X"
+$loader->displayErrorLine = true;
+//Throw an exception when a warning happens
+$loader->throwOnWarning = true;
+//Retrieve the warnings
+$loader->getWarnings();
+```
+
 This package includes the following loaders:
 
 - `MoLoader`
 - `PoLoader`
+- `StrictPoLoader`
 
 And you can install other formats with loaders and generators:
 

src/Generator/PoGenerator.php

@@ -65,6 +65,18 @@ public function generateString(Translations $translations): string
 
             $prefix = $translation->isDisabled() ? '#~ ' : '';
 
+            if ($context = $translation->getPreviousContext()) {
+                $lines[] = sprintf('%s#| msgctxt %s', $prefix, self::encode($context));
+            }
+
+            if ($original = $translation->getPreviousOriginal()) {
+                $lines[] = sprintf('%s#| msgid %s', $prefix, self::encode($original));
+            }
+
+            if ($plural = $translation->getPreviousPlural()) {
+                $lines[] = sprintf('%s#| msgid_plural %s', $prefix, self::encode($plural));
+            }
+
             if ($context = $translation->getContext()) {
                 $lines[] = sprintf('%smsgctxt %s', $prefix, self::encode($context));
             }

src/Loader/MoLoader.php

@@ -4,7 +4,6 @@
 namespace Gettext\Loader;
 
 use Exception;
-use Gettext\Translation;
 use Gettext\Translations;
 
 /**