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:

1
2

{{< translate "bissetii.i18n" "this" "list.Section.Description" >}}
{{< translate "bissetii.i18n" "zh-hans" "list.Section.Description" >}}

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:

  1. 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 for layouts/partials/my-partial.html.
  2. If sequence 1 fails, then it will parse the content as Markdown format.
  3. 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:

  1. ISO 639-1
  2. ISO 3166-1 Alpha 2
  3. ISO 15924

If we follow the example above, the value can be any of the following:

  1. en = explictly select en language directory.
  2. zh-hans = explictly select zh-hans langauge directory.
  3. 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:

1
2
3
4
5
6
7
8

# This is Markdown Heading
Your normal text here.

{{< translate "bissetii.i18n" "this" "list.Section.Description" >}}

{{< translate "bissetii.i18n" "zh-hans" "list.Section.Description" >}}

## Back to Markdown

This will render the output as:

1
2
3
4
5
6
7
8
9

<h1>This is Markdown Heading</h1>
<p>Your normal text here.</p>

In case you are looking up for something in this topic, here are some of the
available content ready for you:

ๅฆ‚ๆžœๆ‚จๆƒณๅœจ่ฟ™ไธช่ฏ้ข˜้‡Œๅฏปๆ‰พไธ€ไบ›ไป”็ป†็š„ๅ†…ๅฎน๏ผŒ่ฟ™้‡Œๅ‡†ๅค‡ไบ†ไธ€ไบ›็ฎ€ๅ•็›ฎๅฝ•่ฎฉๆ‚จๅฏปๆ‰พๅ’Œ่ฟ‡็›ฎ๏ผš

<h2>Back to Markdown></h2>

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.