Multilingual internal references in the documentation

This article explains why you should systematically use the [{}->artN] short-cut syntax when referencing article N in the documentation, regardless of the languages of the calling or called articles.

Version SPIP 2.0, having introduced the possibility to overload the processes for the hreflang in short-cuts, this current site devoted to the multilingual documentation for SPIP now offers a very simple method for referencing its own internal articles.

Previously, if an article A referenced another article B within the documentation, translators would be faced with a difficult situation that is easily overlooked and forgotten later on. They would first translate A to obtain another article, let’s call it C, which would still make an explicit reference to B, since they would not have the URL of the translation of B given as it doesn’t exist yet. By the time that B actually does get translated as D, then finally published, the memory that C contains a reference to B that needs to be replaced as D as every chance of being forgotten.

From now on, translators of the documentation absolutely must use the [{}->artN] notation when referencing article N in the documentation, thus allowing translators to recopy that short-cut link without ever needing to update it later. In fact what happens now, is that if article N does not exist in the same language as the text that includes the short-cut link, then the link will be converted into the URL for article N (which is the best fall-back condition we can make), but if there is actually a translation in the correct language, then the short-cut link will be converted into a URL for the other translated article instead. More precisely, this behaviour will be always observed for a reference in the private zone, whereas the public site adds a supplementary constraint in that the new translation must be actually published itself too, so that the generated URL is actually valid.

How is this made possible ? In fact, SPIP has for a long time permitted the use of braces to specify the value of the hreflang attribute. But SPIP 2.0 now also interprets a pair of empty braces as a hreflang equal to the language of the text that contains the short-cut. The overloaded function introduced for this site simply consists of looking to see if the article designated by the short-cur exists in the language indicated by the hreflang. If this is the case, then the short-cut for ->artN is replaced by one for ->artP, where P is the published translation of N.

Author Mark Published : Updated : 26/10/12

Translations : català, corsu, English, Español, français, Nederlands