Adding Translations for Multi-lingual Labels and Code Snippets - ΩJr. Publizjr Creates Web PagesLanguage-aware Publizjr templates rely on translations to show labels in the correct language. You can also use them to add code snippets.
This article tells webmasters and authors how to use translations. It also tells PHP programmers when to use extensibility, instead.
All Publizjr web page generator templates suffer a drawback that has plagued all discussion forums, content management sytems and page publication systems with which we are familiar: how to translate non-editorial labels without having to program for each supported language?
Several of the forums, CMS-es and PPS-es we have seen employed the same solution: provide a separate bank of pre-translated labels, and have the template select the correct label in the correct language.
Publizjr does the same thing.
Usually they appear as headers above page sections. For instance, the text “Explore:” in the page links below is a non-editorial label.
Sometimes they contain HTML code, like the page comments at the bottom of this web page, and the vCard which shows the page author’s information.
And sometimes they contain bits of PHP programming, like Publizjr’s search form and its social sharing buttons.
The Required Parts Download (available in the Installation Instructions) includes a prefilled translations folder. We expect site administrators to deny access to this folder for web page content authors: letting just anyone access them can wreak serious havoc for the website.
Inside the translations folder live language-specific folders. They are named after the languages the site wishes to support: “en”, “nl”, “es”, “sv”, etc. These abbreviations are defined by the language designation protocol used in the HTTP protocol, which means that every decent web browser will disclose its user’s (the site visitor’s) language preferences. (Read up on the details of the HTML_Accept_Language HTTP header.)
Then unfortunately, Publizjr needs to duplicate the labels of the default language folder into the translations folder itself, in case it is incapable of matching its translation language folders with the site visitor’s language preferences.
A lot of Publizjr 2’s public methods use exactly the same call, making php templates that use Publizjr 2 for their page object a lot cleaner and easier to maintain than those using Publizjr 1.
Using the language-aware class PublizjrMultilanguagePage to generate your web page makes this function “addTranslation()” (and many others) language-aware.
If you would rather throw the translation’s contents into a variable for later use, call a different function:
The difference between the translations and the extensibility is that the first is meant to affect the entire web site, whereas the latter should be available for a single specific web page.
For instance: in our test suite for zjrJS, the cross-browser javascript library, each API method test page sports its own test code. That test code should work on that specific test page, only, and thus is suitable for implementation as extensibility.
In contrast, Publizjr’s search form is meant to be shown on every web page in the site, and thus is more suitable to be implemented as a translation.
Several of the forums, CMS-es and PPS-es we have seen employed the same solution: provide a separate bank of pre-translated labels, and have the template select the correct label in the correct language.
Publizjr does the same thing.
What is a Non-Editorial Label?
This is a small piece of text that the web page will display, over which the page’s content author has little to no influence.Usually they appear as headers above page sections. For instance, the text “Explore:” in the page links below is a non-editorial label.
Sometimes they contain HTML code, like the page comments at the bottom of this web page, and the vCard which shows the page author’s information.
And sometimes they contain bits of PHP programming, like Publizjr’s search form and its social sharing buttons.
Where are these labels stored?
For Publizjr, we store them as separate text files in a folder named “translations”, which by default lives in the site root. (Note: Publizjr 2 allows template programmers to configure where this folder lives.)The Required Parts Download (available in the Installation Instructions) includes a prefilled translations folder. We expect site administrators to deny access to this folder for web page content authors: letting just anyone access them can wreak serious havoc for the website.
Inside the translations folder live language-specific folders. They are named after the languages the site wishes to support: “en”, “nl”, “es”, “sv”, etc. These abbreviations are defined by the language designation protocol used in the HTTP protocol, which means that every decent web browser will disclose its user’s (the site visitor’s) language preferences. (Read up on the details of the HTML_Accept_Language HTTP header.)
Then unfortunately, Publizjr needs to duplicate the labels of the default language folder into the translations folder itself, in case it is incapable of matching its translation language folders with the site visitor’s language preferences.
How does my web page know which label to show?
It knows that because it is programmed into its generator template. For Publizjr 2, a known translation can be added to a web page by the following function call:$page->addTranslation( "morelinks" );A lot of Publizjr 2’s public methods use exactly the same call, making php templates that use Publizjr 2 for their page object a lot cleaner and easier to maintain than those using Publizjr 1.
Using the language-aware class PublizjrMultilanguagePage to generate your web page makes this function “addTranslation()” (and many others) language-aware.
If you would rather throw the translation’s contents into a variable for later use, call a different function:
$label = $page->readTranslation( "morelinks", "Explore:" );
print( "<h2>$label</h2>" );When to use Extensibility instead?
Publizjr 2 lets web page content authors extend their pages by default, allowing them to add bits of page-specific javascript, cascading style sheets, and HTML. (Read more about how Extensibility works in Publizjr.)The difference between the translations and the extensibility is that the first is meant to affect the entire web site, whereas the latter should be available for a single specific web page.
For instance: in our test suite for zjrJS, the cross-browser javascript library, each API method test page sports its own test code. That test code should work on that specific test page, only, and thus is suitable for implementation as extensibility.
In contrast, Publizjr’s search form is meant to be shown on every web page in the site, and thus is more suitable to be implemented as a translation.
What question did we miss?
If you have a question pertaining to Publizjr translations, please let us know using the page comments below?Interested?
Let's meet for coffee or over lunch. Talk to me using this form.