Culture

Currency symbols and the names of days and months depend on the country and language a document is written for. ReportingCloud formats date and currency values by a culture that each merge request can set, so one template creates invoices in dollars for the United States and in euros for Germany. The culture is the culture property of the merge settings, and the template only says which fields are currency or date values.

The format of a field is set in the template, as Merge Fields shows, and the culture is one of the options that Merge Settings lists.

What the Culture Changes

culture is a string property of the mergeSettings object. It specifies the culture of the merge for date and currency values:

• Currency. A merge field formatted as currency shows the currency symbol of the culture: the euro sign (€) with "de-DE", the dollar sign ($) with "en-US".
• Long date formats. Date formats that spell out the names of days and months show them in the language of the culture.
• Numbers in the data. The data is read in the culture as well: with "de-DE", a value such as "1234.5" isn't read as a number and is merged as it stands.
• Default. Without culture, the merge uses "en-US", English for the United States.

The value is a language culture name, mostly a language code and a country or region code joined by a hyphen, such as "fr-FR" for French in France or "de-DE" for German in Germany.

Format a Field as Currency

The culture only affects fields that are formatted as currency or date values in the template. The sample template has a table with a merge block named items, whose row holds the merge fields id and price:

To format price as currency in the template editor, open the Merge Field Options dialog of the field, check Numeric format and type C:

The format belongs to the field and stays the same for every culture. Which currency symbol it produces is decided by the culture of the request.

Merge With a Culture

The following body merges two prices into the template and sets the culture to German in Germany. Save it as merge.json:

{
  "mergeData": [
    {
      "items": [
        { "id": 1, "price": 12.5 },
        { "id": 2, "price": 1250 }
      ]
    }
  ],
  "mergeSettings": { "culture": "de-DE" }
}

Then send it to POST /v1/document/merge with the template, saved in the template storage as price_list.tx:

curl -X POST "https://api.reporting.cloud/v1/document/merge?templateName=price_list.tx&returnFormat=PDF" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @merge.json \
  -o result.json

jq -r '.[0]' result.json | base64 -d > prices.pdf

The prices in prices.pdf carry the euro sign. Send the same body with "en-US", or without culture, and they carry the dollar sign.

With the .NET SDK, the package TXTextControl.ReportingCloud, the culture is the Culture property of MergeSettings:

using TXTextControl.ReportingCloud;

ReportingCloud rc = new ReportingCloud(Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY"));

MergeBody mergeBody = new MergeBody
{
    MergeData = new[] { new { items = new[] { new { id = 1, price = 12.5 } } } },
    // A string here; the .NET Framework build of the package takes a CultureInfo
    MergeSettings = new MergeSettings { Culture = "de-DE" }
};

List<byte[]> documents = rc.MergeDocument(mergeBody, "price_list.tx", ReturnFormat.PDF);
File.WriteAllBytes("prices.pdf", documents[0]);

In the PHP SDK, the culture is the key culture of the merge settings array. The Java and Ruby SDKs have no culture setting, as Merge Settings lists.

Show Dates in the Language of the Culture

Long date formats contain the names of days and months. The Date Field Options dialog of the template editor lists such formats, for example dddd, d. MMMM yyyy, which the dialog shows as "Friday, 13. October 2017":

With a culture set in the request, these names appear in its language: the culture "de-DE" gives German names of days and months.

Choose a Culture Name

The culture must be one of the language culture names in Microsoft's Table of Language Culture Names, Codes, and ISO Values, the list Text Control gives for this setting. Its first column holds the names, for example:

The PHP SDK checks the value against the same table and rejects a culture name that isn't in it.

Next Steps

• Merge Fields: the numeric and date formats of a merge field.
• Merge Settings: culture and the other options of the merge.
• Templates and Merging: what to check when dates or currencies have the wrong format.