anchor.diff: -= Internationalization Overview
  += Internationalization overview
   
  -Kill Bill was designed to support merchants and their customers (user account, or also referred to as 'user' or 'account' in this documentation) across different countries. In order to support that, there are a lot of different aspects that need to be covered ranging from character set, timezones, multiple currencies, locale, and ability to support multiple languages for all customer-visible data (e.g invoices).
  +Kill Bill was designed to support merchants and their customers (user account, or also referred to as 'user' or 'account' in this documentation) across different countries. In order to support that, there are a lot of different aspects that need to be covered ranging from character sets, timezones, multiple currencies, locales, and the ability to support multiple languages for all customer-visible data (e.g invoices).
   
  -In addition, these features must work indepently for the various tenants: A given merchant assigned in a given Kill Bill tenant must be able to configure the system differently than another merchant in a separate tenant.
  +In addition, these features must work independently for the various tenants: a given merchant assigned to a given Kill Bill tenant must be able to configure the system differently than another merchant in a separate tenant.
   
   == Timezones
   
  -Supporting multiple timezones comes into play when a user needs to interract with the system and then later when the system computes state for this user:
  +Supporting multiple timezones comes into play when a user needs to interact with the system and then later when the system computes state for this user:
   
  -* A user cancels a subscription and needs to provide a date (requested cancellation date). That date must be interpreted by the system in the user account timezone
  -* Subsequently, when the system computes the next invoices for instance, that one must include all the items for the period of time reflected in the invoice and as seen by the user.
  +* A user cancelling a subscription needs to provide a date (requested cancellation date). That date must be interpreted by the system in the user account timezone
  +* Subsequently, when the system computes the next invoice for instance, it must include all the items for the period of time reflected by the invoice and as seen by the user.
   
  -An example would be a user creating a monthly subscription on january 1st 2015 but from a timezone in PST (UTC-8). So the action may actually happen at a specific point in time such as  2015-01-02T04:00:00.000Z. The system must correctly understand that the provided date needs to be interpreted in the user timezone so that when the user receives its first invoice he sees a billing period ranging from 2015-01-01 to 2015-02-01. If the user then decides to cancel his subscription on the '2015-02-01', the system also needs to make sure this date is interpreted in the user timezone to avoid charging for an extra day; in that case the user only provides a date with no time (api works that way because it is much simpler from his point of view), and so the precise point in time when that cancellation happens needs to be in the 24 hours period of that specified day in the user timezone.
  -
  +An example would be a user creating a monthly subscription on january 1st 2015 but from a timezone in PST (UTC-8). The action will actually happen at a specific point in time such as 2015-01-02T04:00:00.000Z. The system must correctly understand that the provided date needs to be interpreted in the user timezone so that when the user receives its first invoice, he sees a billing period ranging from 2015-01-01 to 2015-02-01. If the user then decides to cancel his subscription on '2015-02-01', the system also needs to make sure this date is interpreted in the user timezone to avoid charging for an extra day; in that case the user only provides a date with no time (the API works that way because it is much simpler from the user point of view), and so the precise point in time when that cancellation happens needs to be in the 24 hours period of that specified day in the user timezone.
   
   More information on the internals of date, you can refer to this http://killbill.io/blog/lets-talk-about-date-and-time[blog post].
   
   == Multiple Currencies
   
  -The Kill Bill catalog allows to specify amounts in different currencies. Each Kill Bill account needs to specify a currency that is used by the system when generating invoices (by looking up the amount of the specified plan for that currency), and that is also used at the time of making a payment. All the credits, later generated for the account will also be in that currency.
  +The Kill Bill catalog allows to specify amounts in different currencies. Each Kill Bill account needs to specify a currency that is used by the system when generating invoices (by looking up the amount of the specified plan for that currency), and that is also used at the time of making a payment. All the credits later generated for the account will also be in that currency.
   
   The system also allows to also use a different currency at the time of making a payment by using a currency converter.
   
   == Locale
   
  -An account is associated a `locale` (e.g `fr_FR`) that is used for extracting localized resources. The system allows to configure the following resource bundles:
  +An account is associated with a `locale` (e.g `fr_FR`) that is used for extracting localized resources. The system allows to configure the following resource bundles:
   
  -* Catalog Resource Bundle: Ability to translate specific catalog strings in different languages (e.g American english `Gold plan` translated as `Plan Or` in french)
  -* Text Translation: Arbitrary text strings in different languages that can then be used later when creating documents out of templates to ensure they are transalated in the language matching the account.
  -
  +* Catalog Resource Bundle: ability to translate specific catalog strings in different languages (e.g American english `Gold plan` translated as `Plan Or` in French)
  +* Text Translation: arbitrary text strings in different languages that can then be used later when creating documents out of templates to ensure they are translated in the language matching the account
   
   Along with the locale, the system allows to configure different types of templates:
   
   * Invoice templates
   * Email templates 
   
  -== Invoice Templates
  +== Invoice templates
   
  -Kill Bill provides an api to retrieve an html invoice (formatted and translated using the account locale). The templating mechanism is based on https://github.com/spullara/mustache.java[mustache]. In order to configure the system, the following steps need to happen:
  +Kill Bill provides an API to retrieve an html invoice (formatted and translated using the account locale). The templating mechanism is based on https://github.com/spullara/mustache.java[mustache]. In order to configure the system, the following steps need to happen:
   
  -* Upload the translation for all the supported locale
  -* Upload the catalog translation for all the locale (if required)
  +* Upload the translation for all the supported locales
  +* Upload the catalog translation for all the locales (if required)
   
   Example for the locale `fr_FR`:
   
  
positive.code: [source,bash]
  ----
  curl -v \
  -u admin:password \
  -H "X-Killbill-ApiKey: bob" \
  -H "X-Killbill-ApiSecret: lazar" \
  -H 'X-Killbill-CreatedBy: admin' \
  -H "Content-Type: text/plain" \
  -X POST \
  --data-binary @$SOME_PATH_PREFIX/InvoiceTranslation_fr_FR.properties \
  http://127.0.0.1:8080/1.0/kb/invoices/translation/fr_FR
  ----
  
  [start=2]
  
negative.code: companyAddress=P.O. Box 1234
  companyCityProvincePostalCode=Springfield
  companyCountry=USA
  companyUrl=http://kill-bill.org
  
  invoiceItemBundleName=Armes
  invoiceItemDescription=Description
  invoiceItemServicePeriod=Période de facturation
  invoiceItemAmount=Montant
  
  processedPaymentCurrency=(*) Le payment à été payé en
  