Child pages
  • Guide to Locales - Bracket Notation Methods
Skip to end of metadata
Go to start of metadata


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.


Notes:

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

Methods

asis()


Description:

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.

Note:

This method duplicates the asis option for the output method. 

Examples:

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

In these 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:

LanguageRendered string
EnglishThank you for installing cPanel & WHM.
FrenchMerci d'avoir installé cPanel & WHM.

 

boolean()


Description:

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

Examples:

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

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

Note:

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:

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

 

comment()


Description:

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.

Examples:

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

In these 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.

Note:

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:

LanguageRendered string
Englishdoes not begin
FrenchNe commence pas

 

current_year()


Description:

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

Examples:

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

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

LanguageRendered string
EnglishCopyright© 2017.
FrenchCopyright© 2017.

 

datetime()


Description:

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.

Examples:

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

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

LanguageRendered string
English

The current time is Thursday 01 December, 2016.

French

L'heure actuelle est jeudi 01 décembre 2016.

 

format_bytes()


Description:

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.

Examples:

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

In these 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:

LanguageRendered string
English

You have used 820.12 MB of your quota.

French

Vous avez utilisé 820,12 Mo de votre quota.

 

get_locale_name() or get_user_locale_name()


Description:

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

Note:

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

Examples:

$locale->maketext('Your current locale setting is "[get_locale_name]".');
[% locale.maketext('Your current locale setting is "[get_locale_name]".') %]
LOCALE.maketext("Your current locale setting is "[get_locale_name]".");

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

LanguageRendered string
EnglishYour current locale setting is “English”.
French

Votre paramètre local actuel est “français”.

 

is_defined()


Description:

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.

Examples:

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

In these 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.

Notes:

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

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

 

is_future()


Description:

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

Examples:

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

In these 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.

Note:

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:

LanguageRendered string
English
  • Error: Your subscription will expire on Thursday 01 December, 2016.
  • Error: Your subscription expired on Thursday 01 December, 2016.
French
  • Erreur: Votre abonnement expire le jeudi 01 décembre 2016.
  • Erreur: Votre abonnement a expiré le jeudi 01 décembre 2016.

 

join()


Description:

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

Examples:

$locale->maketext('Your order numbers are [join,~, ,_*].', @numbers);
[% locale.maketext('Your order numbers are [join,~, ,_*].', @numbers) %]
LOCALE.maketext("Your order numbers are [join,~, ,_*].", @numbers);

In these examples, the join method uses the values in the @numbers array to create a comma-separated list.

Note:

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:

LanguageRendered string
English

Your order numbers are 1001, 1002, 1003, 1004.

French

Vos numéros de commande sont 1001, 1002, 1003, 1004.

 

list_and()


Description:

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

Examples:

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

In these 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:

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

 

list_and_quoted()


Description:

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

Examples:

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

In these 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:

LanguageRendered string
English

You selected "email", "databases", and "mailing lists".

French

Vous avez sélectionné «courrier électronique», «bases de données» et «listes de diffusion».

 

list_or()


Description:

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

Examples:

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

In these 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:

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

 

list_or_quoted()


Description:

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

Examples:

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

In these 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:

LanguageRendered string
English

You can choose "email", "databases", or "mailing lists".

French

Vous pouvez choisir «e-mail», «bases de données» ou «listes de diffusion».

 

numerate()


Description:

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

Examples:

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

In these 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.

Important:

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:

LanguageRendered string
English
  • Invalid file selected.
  • Invalid files selected.
French
  • Fichier non valide sélectionné.
  • Fichiers non valides sélectionnés.

 

numf()


Description:

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

Examples:

$locale->maketext('Setting applied to [numf,_1] files.', $files);
[% locale.maketext('Setting applied to [numf,_1] files.', $files) %]
LOCALE.maketext("Setting applied to [numf,_1] files.", $files);

In these examples, the numf method displays the $files value in the correct CLDR format for each locale.

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

LanguageRendered string
English

Setting applied to 5,723 files.

French

Réglage appliqué à 5 723 fichiers.

 

output()


Description:

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.

Examples:

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

In these examples, the output method displays not with the strong formatting option.

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

LanguageRendered string
English

Do not press the button!

French

N'appuyez pas sur le bouton!

 

quant()


Description:

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

Note:

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

Examples:

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

In these examples, the quant method displays the $files 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:

LanguageRendered string
English

Setting applied to 5,723.712 files.

French

Réglage appliqué à 5 723,712 fichiers.