With the increasing expansion of Carta to international waters, a big part of our customers are now outside of the US, creating a need for more internationalization (i18n) efforts than ever.

i18n not only unlocks new opportunities and markets for Carta, but improves the user experience for existing clients, making users more comfortable and productive with products and interfaces in their local conventions.

Furthermore, some countries may even require products, software or websites to be localized and follow formatting standards by law like some European countries, Canada, Brazil, etc.

i18n efforts can also help with accessibility and inclusivity, simplify further localization to other languages and build brand trust and loyalty, by showing respect to users' languages and culture, improving Carta's reputation worldwide.

What is important to know about i18n?

i18n involves a series of best practices, design changes, and code changes that need to take place to define a product as internationalized.

i18n efforts take into account anything that can affect the way a user interacts and understands your product; so the use of localized strings, dates, numbers and currencies, and even the cultural significance of specific colors can impact the user experience.

i18n goes from small things such as thousand and decimal separators in numbers to larger things such as reading and writing from right to left instead of left to right.

Some general i18n rules

Avoid hardcoding dates, times, currencies and strings in general. Make use of the existing ink components and hooks for consistency and adaptability.

Ink now offers several different disambiguated and international formats for dates and internal logic for showing correct currency codes.

Some of the internationalized components in ink are: FormattedDate, NewDatePicker, Currency and useFormattedDate.

Dates

Stop relying on libraries such as moment or Date that have their own internal ways of understanding and calculating dates and prefer using ISO 8601 date strings (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ).
Using ISO 8601 strings instead of MM/DD/YYYY strings for storing and interacting with ink components also help avoiding ambiguity and ensures compatibility across systems and locales.
Avoid using ambiguous formats like short and long with numbered months. Prefer disambiguated formats such as condensed, monthCondensed, or condensedWithTime that have the alphabetical month: Jan 1, 2020.
When a date can't be formatted for some reason, show a clear fallback or error message to the user.
Always be explicit with timezones, this ensures dates are correctly shown across entities' data.
If you display the same date/time to multiple users, ensure they see the same value by specifying both time and timezone.
Use timezones from the IANA TZ database (e.g. "America/New_York").

Timezones, localization and precision

As of now, for dates ink allows only for en-GB and en-US locales, but once more are allowed, don't assume a specific locale, use the user's browser's or system's locale to format dates, numbers, and currencies unless there's a strong business need.

When designing or improving data models and APIs, try to make them locale- and timezone-aware.

Here is a list of all available locale codes.

Currencies

Prefer using ISO 4217 currency codes (e.g. USD, EUR, BRL) when there is a mix of currencies to ensure proper understanding.
Don't assume $ will always be understood as American dollars. $ and other currency symbols might be used in more than one country (e.g. American dollar - $, Canadian Dollar - $) causing confusion to users.
Not all currencies use two decimal places, so set decimal precision according to the currency (e.g. 0 for JPY and 2 for USD). Allow dynamic precision when needed.

Timezones, localization and precision

By default, Currency should be using the user's browser or system locale, which is automatically done by the component when no locales are provided.

The locale affects symbol, code, decimal, and thousand separators. Only override the locale prop for strong business reasons.

When designing or improving data models and APIs, try to make them locale-aware.

Texts and translations

When adding translations, check for text expansion, truncation, and layout issues in different languages. Simple sentences in english can take 2+ lines in german, for example.
Don't hardcode strings. Create variables and json objects to store the strings and use i18n solutions for string translation.
When adding translations, use pluralization and gender rules appropriate for the user's language.
Test your UI with various locales, languages, and currencies (english x german, number separators, etc) and look for edge cases.
Always have a sensible fallback for missing translations or formats so the user doesn't have to face blank UI elements or errors.

Colors

Different cultures have different meanings for colors. Be mindful of the colors you're using on the UI when dealing with international products and costumers.

Here are a few resources about colors in the internationalization and localization contexts:

Fallbacks and error handling

If a value cannot be processed or formatted, (invalid date, unknown currency), show a clear fallback or error message. Avoid silent failures and make it obvious when something cannot be displayed due to i18n issues.

Make sure ink components accept the necessary formats for your localized product. If that's not the case, reach out to the #ink channel and make your request, or contribute by opening a PR and adding your format. Don't forget to add tests!