Good Practice

For the WEB

Using Markdown patterns improves readability and facilitates maintenance, both for the translator and for your website scripts that will extract content from it.

For named anchors in a multilingual site, an interesting approach is to "hard-code" links with a Markdown design.

Ex: for an

<h2/>

tag with an anchor



label-in-current-language

LLMs are more efficient than humans at protecting links, and

LSDE

allows you to detect issues between different language versions.


Thus, you can share a link that will work in all languages and use

LSDE

to manage the replacement of a deprecated anchor.




Code Ambiguity

Avoid ambiguity when working with data-oriented models.


Example:


Bad practice:

The term 'key' is not explicit and makes searching for it difficult.



ts
const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		key: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: '<c1>LSDE</c1>',
		key: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		key: 'software:lsge.name',
	},
];


Good practice:

Adopt a unique and consistent convention.


The term 'i18nKey' is very explicit and allows for precise searching of this value via regular expressions ('Regex').


ts
const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		i18nKey: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: '<c1>LSDE</c1>',
		i18nKey: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		i18nKey: 'software:lsge.name',
	},
];



Laziness

Bad ideas are born out of laziness.


Do not try to save keys by performing operations to retrieve content.


Example:


javascript
const [title, subtitle] = t( 'game:game.title' ).split( /[:：]/ );

This is a false good idea, because in some languages, characters can vary, and word order can change.




Tag Format

Minimize design-related code directly within the text, so you can control it from the codebase.


For example, you can indicate an image's location, but not its style or how it should be rendered.


If you need to make design changes, you don't want to be forced to retranslate text into 10 languages just to change a tag's style!



Tags can include an identifier, but adding extra information is generally strongly discouraged and constitutes a bad practice.


Example: Do not do


<img src='url' left />

but rather


<img id=1 />

You will then retrieve the image tag's ID to apply the necessary styles to it in the codebase.


IDs should be used literally and not via their index.


Indeed, in different languages, tags could be moved and no longer correspond to the initial index.


Using natural indexes also introduces complexity for the developer; trying to guess which index the image or tag corresponds to is a real headache.


Therefore, use tags with an identifier when you want to be able to customize them after interpolation.




CSS

For website translation, when you have paragraphs, opt for a minimum height (`min-height`) after translation to avoid visual shifts during language changes.


Ex: `mih={'3lh'}`


This allows you to define a minimum height based on the language that occupies the most lines, thus ensuring a consistent and clean user experience (UX).



Namespace


Always include 'namespaces' in your translation keys, even if you only have one.

This greatly facilitates setting up a Regex pattern to find your keys.


Ex:

game:a.b.c

,

common:a.b.c