{convert:text:from:to}

Description

Converts a string from one character encoding to another, transliterating any character the target encoding cannot represent. Internally it calls iconv with the TRANSLIT flag, so accented letters degrade to their closest plain-ASCII form when you convert to us-ascii (for example, an a-acute is reduced to a plain a, and a c-caron to a plain c). When the source and target encodings are identical the text is returned unchanged. An empty from or to defaults to utf-8. Typical uses: downgrade accented content to plain ASCII for slugs, filenames or legacy systems, or move older windows-1250 content to utf-8.

Parameters

text required default (none)

The string to convert.

from optional default utf-8

Source character encoding of the text, such as utf-8, windows-1250 or us-ascii. Empty means utf-8.

to optional default utf-8

Target character encoding to convert into. Characters the target cannot represent are transliterated to their closest equivalent. Empty means utf-8.

Examples

test{convert:Plain text:utf-8:us-ascii}

ExpectedPlain text

ActualPlain text

Pure ASCII has the same bytes in utf-8 and us-ascii, so nothing changes. convert only alters characters that differ between the two encodings.

test{convert:Hello world:us-ascii:us-ascii}

ExpectedHello world

ActualHello world

When from and to are equal the text is returned verbatim - convert short-circuits before calling iconv, so the value is never touched.

test{convert:{convert2chars:café résumé}:utf-8:us-ascii}

Expectedcafe resume

Actualcafe resume

Converting accented utf-8 text to us-ascii transliterates each letter to its closest unaccented form. Here the input is built from HTML entities via convert2chars so the example stays plain-ASCII in storage; the real input would simply be the accented text.

test{convert:{convert2chars:café}::us-ascii}

Expectedcafe

Actualcafe

Leaving the from parameter empty (the double colon) treats the text as utf-8, the default source encoding. The result is the same as writing utf-8 explicitly.

test{convert:{convert2chars:&Zcaron;lutý k&uring;&ncaron;}:utf-8:us-ascii}

ExpectedZluty kun

ActualZluty kun

A common real use: downgrade accented words to plain ASCII so they are safe in a URL slug or filename. The carons and the ring drop, leaving Zluty kun.

virtual{convert:{full_text.......}:utf-8:windows-1250}

Expected(the field text re-encoded as windows-1250)

Actual{convert:{full_text.......}:utf-8:windows-1250}

The canonical real-world pattern: take a stored field value (utf-8 in AA) and emit it in windows-1250 for a legacy consumer. The output depends on the current item, so this example is illustrative, not a fixed test.

← All expressions