Language Preferences for Applications

People communicate with software through natural languages, such as English, French, and Spanish. Because each person has a different preferred language, it's important for applications to track and accommodate individual language preferences.

Link to section

Overview

The following describes how applications that integrate the Square API might accommodate these language preferences in communications. When communicating through a web browser or mobile application, applications can use the language preferences that those devices already provide. For other types of communication, you must have a language preference on file. Example communications include:

  • Sending a daily status email to a Square seller about how the application's functionality was used that day.
  • Printing receipts for a buyer when using hardware associated with your application.
  • Sending a text message to a buyer after they interact with your application.

Square maintains language preferences for each seller that applications can use in communications. By using Square's language preferences, sellers get a consistent language experience when they access your application, other third-party applications, and Square software.

Square manages language preferences using the language_code field at the Location and Merchant levels. These language codes are a subset of the language tags described in RFC 5646 and each identifies a particular language. For example:

  • en-US designates American English.
  • fr-CA designates Canadian French.

The language code has a primary language (such as "en") followed by an optional dialect subtag (such as "US"). If a language code has both parts, the parts are separated by a hyphen (for example, "en-US").

The language_code can be one of the following Square-supported language codes for the country where the location or merchant exists:

  • Australia: en-AU
  • Canada: fr-CA, en-CA
  • France: en, fr
  • Ireland: en-IE
  • Japan: en, ja
  • United Kingdom: en-GB
  • United States: en-US, es-US
  • All other countries: en, es, fr, ja

Use the Locations API to retrieve or update the language_code for each location. You can also manage these locations in the Seller Dashboard. Applications can use this language_code for communications at a location when there's neither a personal nor device language. For example:

  • Printing receipts - When Square Point of Sale (POS) prints a receipt, the buyer generally doesn't have a Square account or a device to select the language preference. So the receipt should be printed in the location's language.
  • Sending emails and other communications - Applications can use the location language when emailing receipts, invoices, or any other communications for a location.

Use the Merchants API to retrieve the language_code for a seller. The merchant language is the ultimate fallback language if the location’s language doesn't apply. For example, if your application sends a daily status report to a seller and applies to all their locations, then it's best to use the language of the overall merchant for the communication.

Link to section

Additional build basics considerations

There are several other introductory topics provided for a new developer to quickly learn the basics of developing applications with Square. For more information, see Basics of Building Applications with Square.