Skip to content

Commit 90f84ec

Browse files
OskarStarkOskarStark
committed
feature #18600 [Translation] Add docs for pseudolocalization translator (jmsche)
This PR was squashed before being merged into the 5.4 branch. Discussion ---------- [Translation] Add docs for pseudolocalization translator Hi, This PR adds docs for the Pseudolocalization translator that was introduced in Symfony 5.2 (so more than 2 years ago). I copied & adapted the blog post that introduced the feature: https://symfony.com/blog/new-in-symfony-5-2-pseudo-localization-translator I hope this is okay :) All configuration formats have been tested locally to ensure it works. Commits ------- 1ee41e8 [Translation] Add docs for pseudolocalization translator
2 parents dba6794 + 1ee41e8 commit 90f84ec

5 files changed

+133
-1
lines changed

‎_images/translation/pseudolocalization-interface-original.png

4.93 KB
Loading

‎_images/translation/pseudolocalization-interface-translated.png

5.6 KB
Loading

‎_images/translation/pseudolocalization-symfony-demo-disabled.png

65 KB
Loading

‎_images/translation/pseudolocalization-symfony-demo-enabled.png

78.6 KB
Loading

‎translation.rst

Lines changed: 133 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -828,7 +828,7 @@ A better policy is to include the locale in the URL using the
828828
{
829829
}
830830
}
831-
831+
832832
.. code-block:: php-attributes
833833
834834
// src/Controller/ContactController.php
@@ -1289,6 +1289,136 @@ adapted to the format required by GitHub, but you can force that format too:
12891289

12901290
The ``yaml-lint`` binary was introduced in Symfony 5.1.
12911291

1292+
Pseudo-localization translator
1293+
------------------------------
1294+
1295+
.. versionadded:: 5.2
1296+
1297+
The pseudolocalization translator was introduced in Symfony 5.2.
1298+
1299+
.. note::
1300+
1301+
The pseudolocalization translator is meant to be used for development only.
1302+
1303+
The following image shows the main menu of the interface of a popular Internet
1304+
service:
1305+
1306+
.. image:: /_images/translation/pseudolocalization-interface-original.png
1307+
1308+
This other image shows the same menu when the user switches the language to
1309+
Spanish. Unexpectedly, some text is cut and other contents are so long that
1310+
they overflow and you can't see them:
1311+
1312+
.. image:: /_images/translation/pseudolocalization-interface-translated.png
1313+
1314+
These kind of errors are very common, because different languages can be longer
1315+
or shorter than the original application language. Another common issue is to
1316+
only check if the application works when using basic accented letters, instead
1317+
of checking for more complex characters such as the ones found in Polish,
1318+
Czech, etc.
1319+
1320+
These problems can be solved with `pseudolocalization`_, a software testing method
1321+
used for testing internationalization. In this method, instead of translating
1322+
the text of the software into a foreign language, the textual elements of an
1323+
application are replaced with an altered version of the original language.
1324+
1325+
For example, ``Account Settings`` is *translated* as ``[!!! Àççôûñţ
1326+
Šéţţîñĝš !!!]``. First, the original text is expanded in length with characters
1327+
like ``[!!! !!!]`` to test the application when using languages more verbose
1328+
than the original one. This solves the first problem.
1329+
1330+
In addition, the original characters are replaced by similar but accented
1331+
characters. This makes the text highly readable, while allowing to test the
1332+
application with all kinds of accented and special characters. This solves the
1333+
second problem.
1334+
1335+
Full support for pseudolocalization was added to help you debug
1336+
internationalization issues in your applications. You can enable and configure
1337+
it in the translator configuration:
1338+
1339+
.. configuration-block::
1340+
1341+
.. code-block:: yaml
1342+
1343+
# config/packages/translation.yaml
1344+
framework:
1345+
translator:
1346+
pseudo_localization:
1347+
# replace characters by their accented version
1348+
accents: true
1349+
# wrap strings with brackets
1350+
brackets: true
1351+
# controls how many extra characters are added to make text longer
1352+
expansion_factor: 1.4
1353+
# maintain the original HTML tags of the translated contents
1354+
parse_html: true
1355+
# also translate the contents of these HTML attributes
1356+
localizable_html_attributes: ['title']
1357+
1358+
.. code-block:: xml
1359+
1360+
<!-- config/packages/translation.xml -->
1361+
<?xml version="1.0" encoding="UTF-8" ?>
1362+
<container xmlns="http://symfony.com/schema/dic/services"
1363+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1364+
xmlns:framework="http://symfony.com/schema/dic/symfony"
1365+
xsi:schemaLocation="http://symfony.com/schema/dic/services
1366+
https://symfony.com/schema/dic/services/services-1.0.xsd
1367+
http://symfony.com/schema/dic/symfony
1368+
https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
1369+
1370+
<framework:config>
1371+
<framework:translator>
1372+
<!-- accents: replace characters by their accented version -->
1373+
<!-- brackets: wrap strings with brackets -->
1374+
<!-- expansion_factor: controls how many extra characters are added to make text longer -->
1375+
<!-- parse_html: maintain the original HTML tags of the translated contents -->
1376+
<framework:pseudo-localization
1377+
accents="true"
1378+
brackets="true"
1379+
expansion_factor="1.4"
1380+
parse_html="true"
1381+
>
1382+
<!-- also translate the contents of these HTML attributes -->
1383+
<framework:localizable-html-attribute>title</framework:localizable-html-attribute>
1384+
</framework:pseudo-localization>
1385+
</framework:translator>
1386+
</framework:config>
1387+
</container>
1388+
1389+
.. code-block:: php
1390+
1391+
// config/packages/translation.php
1392+
use Symfony\Config\FrameworkConfig;
1393+
1394+
return static function (FrameworkConfig $framework) {
1395+
// ...
1396+
$framework
1397+
->translator()
1398+
->pseudoLocalization()
1399+
// replace characters by their accented version
1400+
->accents(true)
1401+
// wrap strings with brackets
1402+
->brackets(true)
1403+
// controls how many extra characters are added to make text longer
1404+
->expansionFactor(1.4)
1405+
// maintain the original HTML tags of the translated contents
1406+
->parseHtml(true)
1407+
// also translate the contents of these HTML attributes
1408+
->localizableHtmlAttributes(['title'])
1409+
;
1410+
};
1411+
1412+
That's all. The application will now start displaying those strange, but
1413+
readable, contents to help you internationalize it. See for example the
1414+
difference in the `Symfony Demo`_ application. This is the original page:
1415+
1416+
.. image:: /_images/translation/pseudolocalization-symfony-demo-disabled.png
1417+
1418+
And this is the same page with pseudolocalization enabled:
1419+
1420+
.. image:: /_images/translation/pseudolocalization-symfony-demo-enabled.png
1421+
12921422
Summary
12931423
-------
12941424

@@ -1322,3 +1452,5 @@ Learn more
13221452
.. _`Translatable Behavior`: https://github.com/KnpLabs/DoctrineBehaviors
13231453
.. _`Custom Language Name setting`: https://docs.lokalise.com/en/articles/1400492-uploading-files#custom-language-codes
13241454
.. _`GitHub Actions`: https://docs.github.com/en/free-pro-team@latest/actions
1455+
.. _`pseudolocalization`: https://en.wikipedia.org/wiki/Pseudolocalization
1456+
.. _`Symfony Demo`: https://github.com/symfony/demo

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy