The String toLocaleLowerCase() method

The toLocaleLowerCase() method returns a new string with the lowercase transformation of the original string, according to the locale case mappings.

Strings in JavaScript are immutable, so the original string is not changed. You get a new one back.

The first parameter represents the locale, but it’s optional (and if omitted, the current locale is used):

'Testing'.toLocaleLowerCase() //'testing'
'Testing'.toLocaleLowerCase('it') //'testing'
'Testing'.toLocaleLowerCase('tr') //'testing'

You can also pass an array of locales, and the best available one is used.

Why does the locale matter?

As usual with internationalization we might not recognize the benefits, but some languages have their own case mapping rules.

The classic example is Turkish. In Turkish, the lowercase of the letter I is not i. It’s ı, the dotless i. Turkish has two separate i letters, dotted and dotless, and each has its own uppercase and lowercase form.

You can see the difference by comparing the two methods:

'ISTANBUL'.toLowerCase() //'istanbul'
'ISTANBUL'.toLocaleLowerCase('tr') //'ıstanbul'

toLowerCase() applies the default Unicode case mappings, so I becomes i. toLocaleLowerCase('tr') knows the Turkish rules and produces ı instead.

For most languages the two methods return the same result. That’s why English-speaking developers rarely notice this method exists.

Similar to the toLowerCase() method, except that does not take locales into consideration.

When would you reach for it?

Use toLocaleLowerCase() when you’re lowercasing text that users see, and you know the language it’s written in. Displaying a Turkish city name in lowercase is the textbook case.

If you’re lowercasing strings for internal comparisons, like normalizing keys or matching URLs, plain toLowerCase() is the better choice. You want stable, predictable output there, not language-dependent output.

A pitfall to watch out for

The trap works in both directions. Suppose you normalize user input with toLocaleLowerCase() and no argument. The method then uses the runtime’s current locale.

Your code can pass every test on your machine and behave differently for a user in Istanbul, because 'INDEX' lowercases to 'ındex' there. The comparison with 'index' fails and the bug is nearly impossible to reproduce locally.

The fix: be explicit. Pass a locale when the text belongs to a language, or use toLowerCase() when you need the same result everywhere.