Arguments allow you to contextualize your texts to different situations. Within each argument is a set of text options that could be used and the logic for how the marketplace system should determine which option to choose.

Writing arguments is useful when you want to display or handle information that varies, such as pluralization or time format. Typically, you would need to write a separate text for each possible situation; however, arguments allow you to write a single email text and place within it all the relevant options.

An argument can be simple, when there is only one option, or complex, when there are multiple options. Complex arguments contain multiple options within a single argument and they contain the logic for what determines the correct option in a given situation.

Complex arguments are written in the following way: {variable, type, format}.

Arguments in Sharetribe use ICU format, which is a set of software libraries that help software systems format texts properly according to subtleties of a specific language and locale. ICU stands for International Components for Unicode. You can review the technical documentation here for a full overview of arguments’ capabilities.

You can use the following arguments in your email notifications: variables, which are simple arguments, or pluralization, date formats, and currency formats, which are complex arguments. Let’s look at each in detail and see how they work.

Within the value portion of an email text (that is the text itself), variables are used to input information from your marketplace into the email text. Variables are always placed within curly brackets like so {variable}.

An example variable is {listingTitle}. When used, the variable is replaced by the title of the listing involved in the transaction. For example, in a transaction about a listing titled “My awesome bike”, any email text where {listingTitle} variable is used will be replaced by “My awesome bike.”

Available variables depend on the email. Each email has a set of pre-defined variables that you can use. If a variable is already used in a particular email notification, you can use it in other parts of the same email. If it is not in use in a particular email notification, you would need to use custom code to add it there.

Here is a list of the most common variables and what they mean:

You can use arguments to make words plural or singular depending on context. Pluralizing requires a complex argument with 3 parts:

Let’s look at an example of an email text where a pluralization argument is made:

The pluralization argument is: {multiplier, plural, one {day} other {days}}.

multiplier is the variable. It is the placeholder that gets filled depending on what the pluralization argument determines is the correct text.

plural is the type. We are transforming the variable into its singular or plural form.

one {hour} other {hours} tells us the rules for what format to use. If there is an amount of one, use “hour”. In all other situations, use “hours”.

The example above uses English and its pluralization rules. They are pretty simple (exceptions notwithstanding): if you have one of something, use the singular, if you have more than one (any “other” case), use the plural.

Different languages have different pluralization rules, and they can all be supported by arguments. If you are translating your email texts into another language, please consult the technical documentation for ICU arguments to understand the different rules you can specify in the format part of a pluralization argument.

You can use arguments to format dates in your emails. You should use these arguments to ensure that dates are presented in your emails according to the convention of your marketplace language and locale. Your marketplace language and locale affects partly how dates are formatted in your emails; but you must change that argument using the email texts editor.

Date arguments are complex arguments with 3 parts:

Let’s look at an example of an email text where a date argument is made:

The date argument is: {date,date,::hmmaYYYYMMMd}.

date is the variable. It is the value that gets presented according to the formatting rules specified in the argument. The value comes from the date or dates chosen by the customer in their booking.

date is the type of argument we are making. Yes, it is confusing that the variable and argument type use the same word.

::hmmaYYYYMMMd is how the date variable should be presented. You have the following pieces available to you:

Note the double colon (::) ahead of the presentation format. You must include it before writing the presentation format in a date argument.

You can use arguments to format how monetary amounts are presented in your emails. Presenting currency properly takes two arguments: a simple argument and a complex argument. The simple argument gives you the currency symbol of your marketplace. The complex argument gives the amount of money in the transaction as well as how it is formatted.

Let’s look at an example of an email text where a pluralization argument is made:

Previously, we looked at the pluralization argument in this email text. Now we will consider the currency argument, which is: {currency} {amount,number,::.00}

{currency} is a standalone variable or simple argument. It is the placeholder for your marketplace currency symbol, like $ for USD.

amount is the total money in the transaction, presented as a number. It comes from the calculated total value of the transaction in your marketplace.

number is the type of transformation we are making. We are transforming a number, since amount is a number.

::.00 is how the amount variable should be presented in the email text. In this case, the amount number should gain a “.” and “00” behind it.

Note the double colon (::) ahead of the presentation format. You must include it before writing the presentation format in a number argument.