@@ -1314,6 +1314,132 @@ adapted to the format required by GitHub, but you can force that format too:
13141314
13151315 $ php vendor/bin/yaml-lint translations/
13161316
1317+
1318+ ------------------------------
1319+
1320+ .. note ::
1321+
1322+ The pseudolocalization translator is meant to be used for development only.
1323+
1324+ The following image shows the main menu of the interface of a popular Internet
1325+ service:
1326+
1327+ .. image :: /_images/translation/pseudolocalization-interface-original.png
1328+
1329+ This other image shows the same menu when the user switches the language to
1330+ Spanish. Unexpectedly, some text is cut and other contents are so long that
1331+ they overflow and you can't see them:
1332+
1333+ .. image :: /_images/translation/pseudolocalization-interface-translated.png
1334+
1335+ These kind of errors are very common, because different languages can be longer
1336+ or shorter than the original application language. Another common issue is to
1337+ only check if the application works when using basic accented letters, instead
1338+ of checking for more complex characters such as the ones found in Polish,
1339+ Czech, etc.
1340+
1341+ These problems can be solved with `pseudolocalization `_, a software testing method
1342+ used for testing internationalization. In this method, instead of translating
1343+ the text of the software into a foreign language, the textual elements of an
1344+ application are replaced with an altered version of the original language.
1345+
1346+ For example, ``Account Settings `` is *translated * as ``[!!! Àççôûñţ
1347+ Šéţţîñĝš !!!] ``. First, the original text is expanded in length with characters
1348+ like ``[!!! !!!] `` to test the application when using languages more verbose
1349+ than the original one. This solves the first problem.
1350+
1351+ In addition, the original characters are replaced by similar but accented
1352+ characters. This makes the text highly readable, while allowing to test the
1353+ application with all kinds of accented and special characters. This solves the
1354+ second problem.
1355+
1356+ Full support for pseudolocalization was added to help you debug
1357+ internationalization issues in your applications. You can enable and configure
1358+ it in the translator configuration:
1359+
1360+ .. configuration-block ::
1361+
1362+ .. code-block :: yaml
1363+
1364+ # config/packages/translation.yaml
1365+ framework :
1366+ translator :
1367+ pseudo_localization :
1368+ # replace characters by their accented version
1369+ accents : true
1370+ # wrap strings with brackets
1371+ brackets : true
1372+ # controls how many extra characters are added to make text longer
1373+ expansion_factor : 1.4
1374+ # maintain the original HTML tags of the translated contents
1375+ parse_html : true
1376+ # also translate the contents of these HTML attributes
1377+ localizable_html_attributes : ['title']
1378+
1379+ code-block :: xml
1380+
1381+ <!-- config/packages/translation.xml -->
1382+ <?xml version =" 1.0" encoding =" UTF-8"
1383+ <container xmlns =" http://symfony.com/schema/dic/services"
1384+ xmlns : xsi =" http://www.w3.org/2001/XMLSchema-instance"
1385+ xmlns : framework =" http://symfony.com/schema/dic/symfony"
1386+ xsi : schemaLocation =" http://symfony.com/schema/dic/services
1387+ https://symfony.com/schema/dic/services/services-1.0.xsd
1388+ http://symfony.com/schema/dic/symfony
1389+ https://symfony.com/schema/dic/symfony/symfony-1.0.xsd" >
1390+
1391+ <framework : config >
1392+ <framework : translator >
1393+ <!-- accents: replace characters by their accented version -->
1394+ <!-- brackets: wrap strings with brackets -->
1395+ <!-- expansion_factor: controls how many extra characters are added to make text longer -->
1396+ <!-- parse_html: maintain the original HTML tags of the translated contents -->
1397+ <framework : pseudo-localization
1398+ accents =" true"
1399+ brackets =" true"
1400+ expansion_factor =" 1.4"
1401+ parse_html =" true"
1402+ >
1403+ <!-- also translate the contents of these HTML attributes -->
1404+ <framework : localizable-html-attribute >title</framework : localizable-html-attribute >
1405+ </framework : pseudo-localization >
1406+ </framework : translator >
1407+ </framework : config >
1408+ </container >
1409+
1410+ code-block :: php
1411+
1412+ // config/packages/translation.php
1413+ use Symfony\Config\FrameworkConfig;
1414+
1415+ return static function (FrameworkConfig $framework) {
1416+ // ...
1417+ $framework
1418+ ->translator()
1419+ ->pseudoLocalization()
1420+ // replace characters by their accented version
1421+ ->accents(true)
1422+ // wrap strings with brackets
1423+ ->brackets(true)
1424+ // controls how many extra characters are added to make text longer
1425+ ->expansionFactor(1.4)
1426+ // maintain the original HTML tags of the translated contents
1427+ ->parseHtml(true)
1428+ // also translate the contents of these HTML attributes
1429+ ->localizableHtmlAttributes(['title'])
1430+ ;
1431+ };
1432+
1433+
1434+ readable, contents to help you internationalize it. See for example the
1435+ difference in the `Symfony Demo `_ application. This is the original page:
1436+
1437+ .. image :: /_images/translation/pseudolocalization-symfony-demo-disabled.png
1438+
1439+ And this is the same page with pseudolocalization enabled:
1440+
1441+ .. image :: /_images/translation/pseudolocalization-symfony-demo-enabled.png
1442+
13171443Summary
13181444-------
13191445
@@ -1351,3 +1477,5 @@ Learn more
13511477.. _`Machine object format` : https://www.gnu.org/software/gettext/manual/html_node/MO-Files.html
13521478.. _`QT Translations TS XML` : https://doc.qt.io/qt-5/linguist-ts-file-format.html
13531479.. _`GitHub Actions` : https://docs.github.com/en/free-pro-team@latest/actions
1480+ .. _`pseudolocalization` : https://en.wikipedia.org/wiki/Pseudolocalization
1481+ .. _`Symfony Demo` : https://github.com/symfony/demo
0 commit comments