translate
Shortcode
translate
shortcode is a Bissetii specific tool to obtain a particular text or
partials from a language dictionary inside data/
directory. The design allows
the use of various format to render the final results.
Example usage:
|
|
This shortcode is available starting from v1.13.0
.
Heads-Up
While the shortcode is useful, it breaks the Markdown syntax conventions due to Hugo specific shortcode feature. Therefore, when using other Markdown renderer, these shortcodes would be rendered as text instead of HTML code fragments.
Also, be careful and stay safe while using this shortcode. It allows any form of HTML to be embedded into your Markdown page.
Using translate
translate
shortcode is making use of Hugo’s data/
directory instead of the
original Hugo
i18n
feature. You are free to use that original feature instead of this shortcode.
The reason behind this shortcode is it allows one to develop a more organized
way to organize the dictionary inside data/
directory while maintaining the
translation flexiblity from Hugo i18n feature.
Another good reason is that this shortcode allows various rendering format. The parsing format sequences are:
- It first reads the value as a partial filepath. If the partial file is found,
it will parse the partial file instead. Example
my-partial.html
forlayouts/partials/my-partial.html
. - If sequence 1 fails, then it will parse the content as Markdown format.
- If there are reported HTML errors in sequence 2, then it will finally parse the content as HTML format.
It is the content creators' responsibility to ensure the contents are compatible
across multiple output formats (e.g. Accelerated Mobile Page: amp
).
Shortcode Parameters
Since this is a HTML renderer in Markdown file, you want to call in the
shortcode using the <
symbol instead of %
. The brackets are as follow:
The shortcode follows the following parameters pattern:
{{< translate "<dict>" "<lang>" "<query>" >}}
Dictionary (<dict>
)
The 1st parameter is the source of your multi-language dictionary. The 1st-level
sub-directory MUST be language oriented. For example, Bissetii’s default
bissetii/i18n
dictionary is arranged as follows:
data/bissetii/i18n/
โโโ en/
โย ย โโโ list.toml
โโโ zh-hans/
โโโ list.toml
Language (<lang>
)
The 2nd parameter is the selected language. This will select the 1st-level
sub-directory from the given dictionary. For content compatibility, this
parameter accepts a special value called "this"
which in turns, select the
page’s current language instead.
You can freely provide your own language directory. Although given with that freedom, Bissetii recommends you stick to:
If we follow the example above, the value can be any of the following:
en
= explictly selecten
language directory.zh-hans
= explictly selectzh-hans
langauge directory.this
= select the language directory using the current page’s language code.
Query (<query>
)
The 3rd parameter is your translation query. This will select the data after the selected 1st-level sub-directory (language). Here, you are free to use your query based on your defined data TOML file.
The TOML data file and data structure MUST be consistent across langauges. If we continue the example above, inside:
data/bissetii/i18n/en/list.toml
we got:
[Section]
Title = "Available Contents"
Description = """
In case you are looking up for something in this topic, here are some of the
available content ready for you:
"""
data/bissetii/i18n/zh-hans/list.toml
we got:
[Section]
Title = "ๅ
ๅฎน็ฎๅฝ"
Description = """
ๅฆๆๆจๆณๅจ่ฟไธช่ฏ้ข้ๅฏปๆพไธไบไป็ป็ๅ
ๅฎน๏ผ่ฟ้ๅๅคไบไธไบ็ฎๅ็ฎๅฝ่ฎฉๆจๅฏปๆพๅ่ฟ็ฎ๏ผ
"""
This allows us to query list.Section.Description
and list.Section.Title
across both en
and zh-Hans
languages.
Examples
Here are some of the examples for using the shortcode using the example data above:
|
|
This will render the output as:
|
|
Conclusion
That’s all about translate
shortcode in Bissetii. If you need more feature or
need to report a bug, please feel free to file an issue at our
Issue Section.