5.5 Sorting Lists

Sometimes a list is sorted alphabetically to make search easier for the visitors, and this property should be preserved in translations. GNUN has specific marks for such lists.

<!-- GNUN-SORT-START -->

This HTML comment marks the begin of the list.

<!-- GNUN-SORT-STOP -->

This comment marks the end of the list.

<!-- GNUN-SORT-NEXT-ITEM -->

This mark separates list items.

The next two marks are optional, they delimit the key to sort items.

<!-- GNUN-SORT-BEGIN-KEY -->

<!-- GNUN-SORT-END-KEY -->

When extracting the keys, all HTML tags are removed, leading and trailing whitespace is trimmed.

Since the items are reordered in translations, webmasters should carefully choose places for the separators: reordering shouldn’t break the page.

The translators can modify the sorting order using HTML comments if needed. For example, let the English text say

<!-- GNUN-SORT-BEGIN-KEY -->
<h3>Afrikaans</h3>
<!-- GNUN-SORT-END-KEY -->

In the PO file, this transforms to an msgstr like

Afrikaans

The translator inserts a comment in the translation:

<!-- boer --> afrikaans

Now the item sorts like ‘boer afrikaans’.

Additional care should be taken when the items have a separator like

<!-- GNUN-SORT-START -->
A |
<!-- GNUN-SORT-NEXT-ITEM -->
B |
<!-- GNUN-SORT-NEXT-ITEM -->
...
<!-- GNUN-SORT-NEXT-ITEM -->
Y |
<!-- GNUN-SORT-NEXT-ITEM -->
Z
<!-- GNUN-SORT-STOP -->

Note that the last item has no separator (‘|’). When translating, make sure that the item to be last in your translation has no separator, and all other items have it.