Development Guides Home >> 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 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 .
  • For in-depth documentation about the Locale::Maketext module's methods and additional options, read CPAN's Locale::Maketext::Utils 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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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 documentation.

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

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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.

• 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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

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:

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

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

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 .
• em — Italicizes the text.
• encode_puny — Encodes the text into punycode .
• 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 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 .

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:

Perl

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

Template Toolkit

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

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:

Perl

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

Template Toolkit

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

JavaScript

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