wml::std::lang(3)

✨ NAME ✨

okay so this is the manual page for wml::std::lang(3) — a member of the EN Tools family — and bestie, it's literally all about Multi-Lingual Support. 🦋

---

🌈 SYNOPSIS 🌈

#use wml::std::lang

<lang:new id=xx [short]>

<lang:area>
(xx) ... (yy) ...
</lang:area>

<lang:set-wildcard ...>

<lang:star: ...*..>
<lang:star:href: index.*.html|index.html>
<lang:star:slice: index.*.html>

<lang:xx>...</lang:xx>
<lang:xx: ...>

<xx>...</xx>
<xx: ...>

<lang:current>
<lang:list>

---

💅 DESCRIPTION 💅

This include file gives you high-level multi-lingual support via Slices. Its whole entire job? Defining the slices "LANG_XX" according to whatever the multi-lingual selection tags say. periodt. 💖

The general intent of this slice-based approach is to use the defined slices in Pass 9 (Slice) through WML's -o option. A typical shebang-line example for using it with a webserver's content negotiation feature goes like this:

#!wml -o (ALL-LANG_*)+LANG_EN:index.html.en \
      -o (ALL-LANG_*)+LANG_DE:index.html.de

And since WML 1.7.0, the <lang:star:slice:> tag is an alternative to that shebang-line. iconic behavior honestly. ✨

Before you can use a language, you have to define the corresponding tags via <lang:new>. For instance, when you want to use the languages english and german, you'd go:

<lang:new id=en>
<lang:new id=de>

Then the following tags are defined:

<lang:en>...</lang:en>
<lang:de>...</lang:de>
<lang:en: ...>
<lang:de: ...>

i.e. for both languages a container tag and a simple tag get defined. The container tag is more readable while the simple tag is nicer for short variants. And when the names lang:xx are still too large for you, you can use the short attribute to <lang:new>:

<lang:new id=en short>
<lang:new id=de short>

which then leads to the definition of the shortcut variants:

<en>...</en>
<de>...</de>
<en: ...>
<de: ...>

Additionally you always have the <lang:area>...</lang:area> container tag available, which provides an alternative way of selecting the language in its body. It automatically surrounds the data between "(xx)" start tags with the corresponding LANG_XX slice. no cap. 🎀

The following are equal:

<lang:xx: Foo><lang:yy Bar>
<lang:xx>Foo</lang:xx><lang:yy>Bar</lang:yy>
<lang:area>(xx)Foo(yy)Bar</lang:area>

Because these three lines internally get expanded to

[LANG_XX:Foo:][LANG_YY:Bar:]
[LANG_XX:Foo:][LANG_YY:Bar:]
[LANG_XX:Foo:][LANG_YY:Bar:]

There is one additional special tag: <lang:star:>. This tag expands its attribute line like the <lang:xx:> tags but multiple times. Actually as much as defined languages exist (<lang:new>!). And in each expansion, the asterisks (=stars) in the data get replaced by the language identifier. ⭐

It is sometimes convenient to use another wildcard, e.g. when defining navigation bars. The <lang:set-wildcard> tag does the job. The attribute becomes the wildcard used in future substitutions. Without an attribute, the default value is restored. You may specify any regular expression, and do not forget to escape special characters (the asterisk is in fact \*).

<lang:set-wildcard "%">
<lang:star: index.%.html>
<lang:set-wildcard>

There's a more specialized variant named <lang:star:href:> which is similar to <lang:star:> but treats its attribute value as a URL part and tries to check if it already exists. If it doesn't exist, the tag expands the value without the star, or an alternative value which can be appended with |alt-value. 🫶

The <lang:star:slice:> is another variant to help writing multi-lingual files quickly. It must come after all occurrences of <lang:new> tags.

<lang:star:slice: index.html.*>

The %BASE form is recognized (see wml(1)) and an empty argument is equivalent to the string "%BASE.*.html". But heads up bestie — note that the use of this tag instead of the WML shebang line prevents WMk from doing its job, because WMk can not guess output filenames in this case. 😭

fr fr, that WMk thing is a real tradeoff, don't sleep on it.

For complex multi-lingual documents, you may want to know in which language text is currently processed. This is achieved with

<lang:current>

which always returns the current language (as defined in <lang:new>) or an empty string when outside of any language portion. The macro

<lang:list>

prints the newline separated list of defined languages. 👑

---

🌸 EXAMPLE 🌸

The following is an example of a webpage index.wml with a multi-lingual header and hyperlink:

#use wml::std::lang
#use wml::std::href

<lang:new id=en short>
<lang:new id=de short>
<lang:star:slice: index.html.*>

<h1><en: Welcome><de: Willkommen></h1>

<href name="The Hyperlink" url="<lang:star: index.*.html>">
<href name="The Hyperlink" url="<lang:star:href: index2.*.html|index2.html>">

When processed via

$ wml index.wml

The following two output files are generated (assuming that index2.html and only index2.de.html exists):

index.html.en:

<h1>Welcome</h1>
<a href="index.en.html">The Hyperlink</a>
<a href="index2.html">The Hyperlink</a>

index.html.de:

<h1>Willkommen</h1>
<a href="index.de.html">The Hyperlink</a>
<a href="index2.de.html">The Hyperlink</a>

---

🎀 AUTHOR 🎀

• Ralf S. Engelschall
  • rse@engelschall.com
  • www.engelschall.com
• Denis Barbier
  • barbier@engelschall.com

---

🦋 REQUIRES 🦋

• Internal: P1, P2, P6, P9
• External: --

---

⭐ SEE ALSO ⭐

• slice(1)

---

and that's a wrap, bestie 💜 this page came from EN Tools, dated 2020-11-29, and it lives at wml::std::lang(3). go forth and be multilingual, you absolute icon 👑✨