[Development Guides Home](/guides) >> [Guide to Locales](/guides/guide-to-locales) >> [Bracket Notation](/guides/guide-to-locales/guide-to-locales-bracket-notation)

# Guide to Locales - Bracket Notation Methods

## Introduction

Bracket notation allows you to customize the localized strings in your custom code. For example, you can use these methods to add formatting to a localized string, or to provide helpful notes and disambiguations to aid translators. This document includes examples for the use of bracket notation in custom applications and interfaces.

* For additional examples of localization in Template Toolkit files, read our [Guide to Template Toolkit](/guides/guide-to-template-toolkit) in cPanel & WHM documentation.
* cPanel & WHM whitelists specific bracket notation methods by default.
  * To use other existing methods or custom methods that you created, you must add them to the [bracket notation whitelist](/guides/guide-to-locales/guide-to-locales-bracket-notation/guide-to-locales-the-bracket-notation-whitelist/).
  * For in-depth documentation about the `Locale::Maketext` module's methods and additional options, read [CPAN's `Locale::Maketext::Utils`](https://metacpan.org/pod/distribution/Locale-Maketext-Utils/lib/Locale/Maketext/Utils.pod#Improved-B) documentation.


By default, cPanel & WHM whitelists the following bracket notation methods:

* `asis`
* `boolean`
* `comment`
* `current_year`
* `datetime`
* `format_bytes`
* `get_locale_name`
* `get_user_locale_name`
* `is_defined`
* `is_future`
* `join`
* `list_and`
* `list_and_quoted`
* `list_or`
* `list_or_quoted`
* `numerate`
* `numf`
* `output`
* `quant`


## Methods

### asis()

This method demarcates non-translatable text in your phrase. Use this method to ensure that your translator correctly handles proper nouns, technical names, and other text.

This method duplicates the `asis` option for the `output` method.

In the following code examples, the `asis` method ensures that the translator will **not** translate the words cPanel & WHM in the string.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `Thank you for installing cPanel & WHM.` |
| French | `Merci d'avoir installé cPanel & WHM.` |


#### Perl


```perl
$locale->maketext('Thank you for installing [asis,cPanel amp() WHM].');
```

#### Template Toolkit


```perl
[% locale.maketext('Thank you for installing [asis,cPanel amp() WHM].') %]
```

#### JavaScript


```javascript
LOCALE.maketext("Thank you for installing [asis,cPanel amp() WHM].");
```

### boolean()

This method allows you to use a Boolean value to conditionally display one of two word or phrase choices within a localized string.

In the following code examples, the `boolean` method uses the `$success` value to determine whether to display `saved` or `did not save` in the translated string.

This method always assigns the second argument (in these examples, `saved`) to a true value (`1`) and the third argument (in these examples, `did not save`) to a false value (`0`).

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `The file saved correctly.` `The file did not save correctly.` |
| French | `Le fichier est enregistré correctement.` `Le fichier n'a pas été enregistré correctement.` |


#### Perl


```perl
$locale->maketext('The file [boolean,_1,saved,did not save] correctly.', $success);
```

#### Template Toolkit


```perl
[% locale.maketext('The file [boolean,_1,saved,did not save] correctly.', $success) %]
```

#### JavaScript


```javascript
LOCALE.maketext("The file [boolean,_1,saved,did not save] correctly.", $success);
```

### comment()

This method embeds comments that only the developer and translator see. Use this method, for example, when the string requires additional context in order to translate it correctly.

In the following code examples, a translator may experience difficulty or confusion due to the apparent sentence fragment. However, because this text appears in a menu of comparison options, the text itself is complete. The comment will assist the translator to correctly handle this unique usage.

In most uses, we strongly recommend that you **only** use title case labels and complete sentences in localized text. For more information, read our [Guide to Locales - Best Practices](/guides/guide-to-locales/guide-to-locales-best-practices) documentation.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `does not begin` |
| French | `Ne commence pas` |


#### Perl


```perl
$locale->maketext('does not begin[comment,comparison option]');
```

#### Template Toolkit


```perl
[% locale.maketext('does not begin[comment,comparison option]') %]
```

#### JavaScript


```javascript
LOCALE.maketext("does not begin[comment,comparison option]");
```

### current_year()

This method displays the current year, in Unicode's Common Locale Data Repository (CLDR) format.

In the following code examples, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `Copyright© 2017.` |
| French | `Copyright© 2017.` |


#### Perl


```perl
$locale->maketext('Copyright© [current_year].');
```

#### Template Toolkit


```perl
[% locale.maketext('Copyright© [current_year].') %]
```

#### JavaScript


```javascript
LOCALE.maketext("Copyright© [current_year].");
```

### datetime()

This method displays the current date and time in the correct format for a locale. To do this, the method uses options from [the `DateTime` CPAN module](https://metacpan.org/pod/DateTime).

* Use this method without arguments to display the current time in `date_format_long` format.
* You can also use this method with the following arguments:
  * First argument:
    * A `DateTime` object.
    * A hash reference of arguments for the `DateTime->new()` method.
    * An epoch for the `DateTime->from_epoch()` method's epoch field.
    * A time zone for the `DateTime` constructors' `time_zone` field.
    * A comma-separated list of two of the above options.
  * Second argument:
    * A string, or code reference that returns a string, for the `DateTime->format_cldr()` method.
    * The name of a `DateTime::Locale` method.


In the following code examples, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `The current time is Thursday 01 December, 2016.` |
| French | `L'heure actuelle est jeudi 01 décembre 2016.` |


#### Perl


```perl
$locale->maketext('The current time is [datetime].');
```

#### Template Toolkit


```perl
[% locale.maketext('The current time is [datetime].') %]
```

#### JavaScript


```javascript
LOCALE.maketext("The current time is [datetime].");
```

### format_bytes()

This method converts a byte count to a human-readable format without the need for external modules. Optionally, you can add a second argument to specify a maximum number of decimal places to display.

In the following code examples, the `$bytes` value will render in human-readable format with two decimal places.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `You have used 820.12 MB of your quota.` |
| French | `Vous avez utilisé 820,12 Mo de votre quota.` |


#### Perl


```perl
$locale->maketext('You have used [format_bytes,_1,_2] of your quota.', $bytes, 2);
```

#### Template Toolkit


```perl
[% locale.maketext('You have used [format_bytes,_1,_2] of your quota.', $bytes, 2) %]
```

#### JavaScript


```javascript
LOCALE.maketext("You have used [format_bytes,_1,_2] of your quota.", $bytes, 2);
```

### get_locale_name() or get_user_locale_name()

This method returns the name of the user's current locale.

The examples below use the `get_locale_name` method. The `get_user_locale_name` method uses identical functionality.

In the following code examples, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `Your current locale setting is “English”.` |
| French | `Votre paramètre local actuel est «français».` |


#### Perl


```perl
$locale->maketext('Your current locale setting is “[get_locale_name]”.');
```

#### Template Toolkit


```perl
[% locale.maketext('Your current locale setting is “[get_locale_name]”.') %]
```

#### JavaScript


```javascript
LOCALE.maketext("Your current locale setting is “[get_locale_name]”.");
```

### is_defined()

This method allows you to check for a defined value in order to conditionally display one of two word or phrase choices within a localized string.

In the following code examples, the `is_defined` method checks whether the `$value` value is defined to determine whether to display `“_1” is an invalid` or `Specify a valid` in the translated string.

* These examples use the first argument as both the value to check and as a displayed variable within the second argument.
* This method always assigns the second argument (in these examples, `“_1” is an invalid`) to a defined value and the third argument (in these examples, `Specify a valid`) to an undefined value.


For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `Error: “boop” is an invalid value.` `Error: Specify a valid value.` |
| French | `Erreur: «boop» est une valeur non valide.` `Erreur: Spécifiez une valeur valide.`` |


#### Perl


```perl
$locale->maketext('Error: [is_defined,_1,“_1” is an invalid,Specify a valid] value.', $value);
```

#### Template Toolkit


```perl
[% locale.maketext('Error: [is_defined,_1,“_1” is an invalid,Specify a valid] value.', $value) %]
```

#### JavaScript


```javascript
LOCALE.maketext("Error: [is_defined,_1,“_1” is an invalid,Specify a valid] value.", $value);
```

### is_future()

This method allows you to use a DateTime value to conditionally display one of two word or phrase choices within a localized string.

In the following code examples, the `is_future` method checks whether the `$expiredate` date has occurred to determine whether to display will expire or expired in the translated string.

This method always assigns the second argument (in these examples, `will expire`) if the date has not yet occurred and the third argument (in these examples, `expired`) if the date has occurred.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `Error: Your subscription will expire soon.` `Error: Your subscription expired.` |
| French | `Erreur : Votre abonnement va bientôt expirer.` `Erreur : Votre abonnement a expiré.` |


#### Perl


```perl
$locale->maketext('Error: Your subscription [is_future,_1,will expire soon,expired].', $expiredate);
```

#### Template Toolkit


```perl
[% locale.maketext('Error: Your subscription [is_future,_1,will expire soon,expired].', $expiredate) %]
```

#### JavaScript


```javascript
LOCALE.maketext("Error: Your subscription [is_future,_1,will expire soon,expired].", $expiredate);
```

### join()

This method joins a set of arguments with a specified character.

In the following code examples, the join method uses the values in the `list_of_numbers` array to create a comma-separated list.

This method always uses the first argument as the separator between items, and the second argument as the list of items to join.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `Your order numbers are 1001, 1002, 1003, 1004.` |
| French | `Vos numéros de commande sont 1001, 1002, 1003, 1004.` |


#### Perl


```perl
$locale->maketext('Your order numbers are [join, , ,_1].', \@list_of_numbers);
```

#### Template Toolkit


```perl
[% locale.maketext('Your order numbers are [join, , ,_1].', list_of_numbers) %]
```

#### JavaScript


```javascript
LOCALE.maketext("Your order numbers are [join, , ,_1].", list_of_numbers);
```

### list_and()

This method joins a set of arguments with the locale's CLDR list pattern for and.

In the following code examples, the `list_and` method uses the values in the `settings` array to create a list that uses the locale's CLDR list pattern for `and`.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `You selected email, databases, and mailing lists.` |
| French | `Vous avez sélectionné les courriels, les bases de données et les listes de diffusion.` |


#### Perl


```perl
$locale->maketext('You selected [list_and,_1].', \@settings);
```

#### Template Toolkit


```perl
[% locale.maketext('You selected [list_and,_1].', settings) %]
```

#### JavaScript


```javascript
LOCALE.maketext("You selected [list_and,_1].", settings);
```

### list_and_quoted()

This method joins a set of arguments with quotes and the locale's CLDR list pattern for and.

In the following code examples, the `list_and_quoted` method uses the values in the `settings` array to create a list that uses quotes and the locale's CLDR list pattern for and.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `You selected “email”, “databases”, and “mailing lists”.` |
| French | `Vous avez sélectionné «courrier électronique», «bases de données» et «listes de diffusion».` |


#### Perl


```perl
$locale->maketext('You selected [list_and_quoted,_1].', \@settings);
```

#### Template Toolkit


```perl
[% locale.maketext('You selected [list_and_quoted,_1].', settings) %]
```

#### JavaScript


```javascript
LOCALE.maketext("You selected [list_and_quoted,_1].", settings);
```

### list_or()

This method joins a set of arguments with the locale's CLDR list pattern for `or`.

In the following code examples, the `list_or` method uses the values in the `settings` array to create a list that uses the locale's CLDR list pattern for `or`.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `You can choose email, databases, or mailing lists.` |
| French | `Vous pouvez choisir des e-mails, des bases de données ou des listes de diffusion.` |


#### Perl


```perl
$locale->maketext('You can choose [list_or,_1].', \@settings);
```

#### Template Toolkit


```perl
[% locale.maketext('You can choose [list_or,_1].', settings) %]
```

#### JavaScript


```javascript
LOCALE.maketext("You can choose [list_or,_1].", settings);
```

### list_or_quoted()

This method joins a set of arguments with quotes and the locale's CLDR list pattern for `or`.

In the following code examples, the `list_or` method uses the values in the `settings` array to create a quoted list that uses the locale's CLDR list pattern for `or`.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `You can choose “email”, “databases”, or “mailing lists”.` |
| French | `Vous pouvez choisir «e-mail», «bases de données» ou «listes de diffusion».` |


#### Perl


```perl
$locale->maketext('You can choose [list_or_quoted,_1].', \@settings);
```

#### Template Toolkit


```perl
[% locale.maketext('You can choose [list_or_quoted,_1].', settings) %]
```

#### JavaScript


```javascript
LOCALE.maketext("You can choose [list_or_quoted,_1].", settings);
```

### numerate()

This method correctly handles the singular and plural versions of your localized text.

In the following code examples, the `numerate` method uses the number of values in the `@files` array to determine whether to use a singular or plural form of file.

To provide the number of values in a variable to the method instead of the variable's value, append `.size` to the end of the variable name.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `Invalid file selected.` `Invalid files selected.` |
| French | `Fichier non valide sélectionné.` `Fichiers non valides sélectionnés.` |


#### Perl


```perl
$locale->maketext('Invalid [numerate,_1,file,files] selected.', @files.size);
```

#### Template Toolkit


```perl
[% locale.maketext('Invalid [numerate,_1,file,files] selected.', @files.size) %]
```

#### JavaScript


```javascript
LOCALE.maketext("Invalid [numerate,_1,file,files] selected.", @files.size);
```

### numf()

This method formats a number in the appropriate CLDR format for each locale.

In the following code examples, the `numf` method displays the `$pick_a_number` value in the correct CLDR format for each locale.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `The value for “pick_a_number” must be a whole number between 1 and 100.` |
| French | `La valeur de «pick_a_number» doit être un nombre entier compris entre 1 et 100.` |


#### Perl


```perl
$locale->maketext('The value for “[_1]” must be a whole number between [numf,_2] and [numf,_3].', "pick_a_number", 1, 100);
```

#### Template Toolkit


```perl
[% locale.maketext('The value for “[_1]” must be a whole number between [numf,_2] and [numf,_3].', "pick_a_number", 1, 100) %]
```

#### JavaScript


```javascript
LOCALE.maketext("The value for “[_1]” must be a whole number between [numf,_2] and [numf,_3].", "pick_a_number", 1, 100);
```

### output()

This method allows you to format specific words or phrases within a localized string. You can use the `output` method with several first arguments.

The following arguments apply various formats to the text that you provide as the third argument:

* `abbr` — Displays an abbreviation with, in HTML contexts, hover text of the non-abbreviated form (the fourth argument).
acronym — Displays an acronym with, in HTML contexts, an `<abbr>` tag that includes the phrase that the acronym represents (the fourth argument).
* `asis` — Applies the `asis` method.
* `asis_for_tests` — Applies the `asis` method. Use this argument for test purposes only.
* `attr or inline` — Assigns an attribute and value (in HTML, a `<span>` tag) which you specify as the third and fourth arguments, respectively.
* `block` — Assigns an attribute and value (in HTML, a `<div>` tag) which you specify as the third and fourth arguments, respectively.
* `class` — Adds a `CSS` class when the locale system renders the text in a `CSS`-compatible format.
* `decode_puny` — Decodes the text from [punycode](https://www.punycoder.com/).
* `em` — Italicizes the text.
* `encode_puny` — Encodes the text into [punycode](https://www.punycoder.com/).
* `img` — Outputs an image (the third argument), or, in non-HTML contexts, the `alt` text for that image (the second argument).
* `strong` — Bolds the text.
* `sub` — Outputs the text as subscript.
* `sup` — Outputs the text as superscript.
* `underline` — Underlines the text.
* `url` — Formats the text as a linked URL.


The following arguments insert special characters into localized text:

* `amp` — An ampersand character (`&`).
* `apos` — A single straight quote (`'`).
* `chr` — Outputs a special character, for which the third argument is the character's [ASCII](http://ascii.cl/) code.
* `gt` — A greater than character (`>`).
* `lt` — A less than character (`<`).
* `nbsp` — A non-breaking space character.
* `quot` — A double straight quote (`"`).
* `shy` — A [soft hyphen](https://en.wikipedia.org/wiki/Soft_hyphen).


In the following code examples, the `output` method displays `not` with the `strong` formatting option.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `Do <strong>not</strong> press the button!` |
| French | `N'appuyez <strong>pas</strong> sur le bouton!` |


#### Perl


```perl
$locale->maketext('Do [output,strong,not] press the button!');
```

#### Template Toolkit


```perl
[% locale.maketext('Do [output,strong,not] press the button!') %]
```

#### JavaScript


```javascript
LOCALE.maketext("Do [output,strong,not] press the button!");
```

### quant()

This method formats a number in the appropriate CLDR format for each locale, and displays appropriate text for the quantity.

This method essentially combines the functionality of the `numerate` and `numf` methods.

In the following code examples, the `quant` method displays the `$file_count` value in the correct CLDR format for each locale, and uses the correct form (singular or plural) of `file`.

For example, these examples might render the following strings after translation:

| Language | Rendered string |
|  --- | --- |
| English | `Setting applied to 5,723 files.` |
| French | `Réglage appliqué à 5 723 fichiers.` |


#### Perl


```perl
$locale->maketext('Setting applied to [quant,_1,file,files].', $file_count);
```

#### Template Toolkit


```perl
[% locale.maketext('Setting applied to [quant,_1,file,files].', $file_count) %]
```

#### JavaScript


```javascript
LOCALE.maketext("Setting applied to [quant,_1,file,files].", $file_count);
```