Forem: Joshua Slate

Deterministic React Avatar Fallbacks

Joshua Slate — Sat, 03 Dec 2022 16:56:48 +0000

Ah, avatars. Everyone on the internet just loves putting their face out there for everyone to see, right? Well, not quite. Often times, especially on engineering teams, you'll see a bunch of colorful squares or circles with peoples' initials in them.

This will be a shorter post, but we're going to explore how we can give each user a consistent background color for their default avatar if they haven't provided a profile picture. As a bonus, we're going to explore adding Gravatar support as well.

Building the Base Avatar Component

Let's start off by building a simple avatar component that first attempts to load in a user's profile picture (if provided), otherwise falls back to showing their initials.

import React, { useEffect, useState } from 'react';

interface Props {
  imageSrc?: string;
  name: string;
}

enum Status {
  Idle = 'idle',
  Loading = 'loading',
  Error = 'error',
  Success = 'success',
}

const Avatar: React.FC<Props> = ({ imageSrc, name }) => {
  const [status, setStatus] = useState<Status>(imageSrc ? Status.Loading : Status.Idle);
  const initials = name
    ?.split(' ')
    .map((chunk) => chunk.charAt(0).toLocaleUpperCase())
    .slice(0, 2)
    .join('');

  useEffect(() => {
    if (imageSrc) {
      setStatus(Status.Loading);

      // Test if the image can be loaded successfully by creating a non-rendered Image element
      // and adding event listeners for a "load" or "error"
      const img = new Image();

      // If the image is loaded successfully, we'll render it
      img.onload = () => {
        setStatus(Status.Success);
      };

      // Otherwise, we'll show the initials
      img.onerror = () => {
        setStatus(Status.Error);
      };

      // Now that the event handlers have been added, set the source to initiate the image load
      img.src = imageSrc;
    }
  }, [imageSrc]);
  const isLoading = status === Status.Loading;
  const hasLoadedImage = status === Status.Success;

  return (
    <div
      style={{
        height: 64,
        width: 64,
        overflow: 'hidden',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        borderRadius: '50%',
        background: '#000',
        color: '#FFF',
        fontWeight: 'bold',
      }}
    >
      {imageSrc && (isLoading || hasLoadedImage) && (
        <img
          alt={name}
          src={imageSrc}
          style={{
            display: isLoading ? 'none' : 'block',
            height: '100%',
            width: '100%',
            objectFit: 'cover'
          }}
        />s
      )}

      {!hasLoadedImage && !isLoading && <span>{initials}</span>}
    </div>
  );
};

export default Avatar;

What we have built so far is an avatar component that has two ways it can display: as the user's initials, or the provided image.

Initially, we hide the img element while we're testing whether the image can be loaded or not. This is particularly handy in the event that you want to default to a Gravatar.

Implementing Gravatar

import md5 from 'crypto-js/md5';

interface Props {
  email: string;
  name: string;
}

/**
 * The GET Gravatar endpoint requires a user's email to be trimmed, lower-cased, and
 * hashed by the MD5 hashing algorithm
 * More information on using Gravatar at https://gravatar.com/site/implement/images/
 */
const getGravatarForEmail = (email: string) => {
  const emailHash = md5(email.trim().toLowerCase()).toString();

  // The `d` search param is very important to our avatar, so an error code is returned when a Gravatar isn't found
  return `https://www.gravatar.com/avatar/${emailHash}?d=404`;
}

If the image fails to load, we simply render the user's initials. Keep in mind that we're using a naïve implementation to get a user's initials in the example above. As noted in my earlier article about internationalization and localization, some languages don't separate words with whitespace. If your application supports users around the world, you may wish to use Intl.Segmenter for this purpose.

So what's next? Well, the example above shows a boring black circle for every user that doesn't have a Gravatar. In order to make things interesting, let's improve the component to give each user one of several colors. We can accomplish this by creating a simple hashing function of our own.

Deterministically Personalizing Avatar Colors

We will want to choose a piece of user data that isn't expected to change much, if at all. Perhaps an ID or email address. That will be the value we hash to determine a background color for the avatar fallback.

const getBackgroundForStringValue = (str: string | undefined, colorOptions: string[]) => {
  const strHashedAsNumber = (str || '')
    .split('')
    .reduce((accum, val) => val.charCodeAt(0) + accum, str?.length || 0);

  return colorOptions[strHashedAsNumber % colorOptions.length];
};

This will return a consistent color value for any given string. Let's walk through a few sample calls.

const ACCENT_COLORS = [
  '#3db378',
  '#b33d5e',
  '#3d87b3',
  '#b3843d',
];

/**
 * When hashed to a number value, the following UUID is strHashedAsNumber = 2310.
 * 2310 % ACCENT_COLORS.length === 2
 * ACCENT_COLORS[2] === '#3d87b3'
 */
getBackgroundForStringValue('fc81deb7-b0f1-4143-8560-187f6c227800', ACCENT_COLORS);

/**
 * When hashed to a number value, the following UUID is strHashedAsNumber = 2480.
 * 2480 % ACCENT_COLORS.length === 0
 * ACCENT_COLORS[0] === '#3db378'
 */
getBackgroundForStringValue('0f0115dd-adb2-40a8-ae9a-39071d61cb27', ACCENT_COLORS);

/**
 * When hashed to a number value, the following UUID is strHashedAsNumber = 2501.
 * 2501 % ACCENT_COLORS.length === 1
 * ACCENT_COLORS[1] === '#b33d5e'
 */
getBackgroundForStringValue('3e757a86-9d2c-42b4-bbfc-01f1a37f514e', ACCENT_COLORS);

Using a function like this, you can ensure that users have their "own" color that is persistent for them without having to manually assign them a color that's stored on their profile in the database or something to that effect.

Putting It All Together

import React, { useEffect, useState } from 'react';
import md5 from 'crypto-js/md5';

interface Props {
  email: string;
  name: string;
}

enum Status {
  Idle = 'idle',
  Loading = 'loading',
  Error = 'error',
  Success = 'success',
}

const getGravatarForEmail = (email: string) => {
  const emailHash = md5(email.trim().toLowerCase()).toString();

  return `https://www.gravatar.com/avatar/${emailHash}?d=404`;
}

// You could use theme context color names instead of a hard-coded array, if you're using something
// like styled-components.
const ACCENT_COLORS = [
  '#3db378',
  '#b33d5e',
  '#3d87b3',
  '#b3843d',
];

const getBackgroundForStringValue = (str: string | undefined, colorOptions: string[]) => {
  const strHashedAsNumber = (str || '')
    .split('')
    .reduce((accum, val) => val.charCodeAt(0) + accum, str?.length || 0);

  return colorOptions[strHashedAsNumber % colorOptions.length];
};

const Avatar: React.FC<Props> = ({ email, name }) => {
  const gravatarSrc = /\S+@\S+\.\S+/.test(email)
    ? getGravatarForEmail(email)
    : '';
  const [status, setStatus] = useState<Status>(gravatarSrc ? Status.Loading : Status.Idle);
  const initials = name
    ?.split(' ')
    .map((chunk) => chunk.charAt(0).toLocaleUpperCase())
    .slice(0, 2)
    .join('');

  useEffect(() => {
    if (gravatarSrc) {
      setStatus(Status.Loading);

      const img = new Image();
      img.onload = () => {
        setStatus(Status.Success);
      };

      img.onerror = () => {
        setStatus(Status.Error);
      };

      img.src = gravatarSrc;
    }
  }, [gravatarSrc]);
  const isLoading = status === Status.Loading;
  const hasLoadedImage = status === Status.Success;

  return (
    <div
      style={{
        height: 64,
        width: 64,
        overflow: 'hidden',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        borderRadius: '50%',
        background: getBackgroundForStringValue(email, ACCENT_COLORS),
        color: '#CBCACAFF',
        fontWeight: 'bold',
      }}
    >
      {gravatarSrc && (isLoading || hasLoadedImage) && (
        <img
          alt={name}
          src={gravatarSrc}
          style={{
            display: isLoading ? 'none' : 'block',
            height: '100%',
            width: '100%',
            objectFit: 'cover'
          }}
        />
      )}

      {!hasLoadedImage && !isLoading && <span>{initials}</span>}
    </div>
  );
};

export default Avatar;

Try it!

Depending on your theme's colors, you may end up with accessibility issues due to insufficient contrast between your background colors and the text color for the initials. You can either be cognizant of the contrast issue when selecting your potential background colors, or you can deal with the issue programmatically by using a library like color to validate that there's enough contrast between your background and font colors, and altering one or the other until an acceptable level is reached.

As always, if I missed something or made a mistake, please reach out to me on Twitter. If you learned something, don't hesitate to share.

Internationalizing and Localizing a React App: i18n Made Easy

Joshua Slate — Thu, 01 Dec 2022 18:02:55 +0000

In the beginning of my career as a software engineer, I worked on several niche B2B products that only dealt with end-users who spoke English and were based in the US. In 2018, that all changed when I got the exciting opportunity to pick up my life and move to Barcelona to work for Typeform. Suddenly, not only was I working with a diverse team of other frontend developers from dozens of different countries, but I was building a product that needed to serve users around the world. From there on, I moved to work at an international financial exchange, where we needed to provide financial data, times and dates, and text content in the language and format that our users were accustomed to, with more than 10 languages supported.

In working with such diverse teams on products that needed to support users around the world, I learned a thing or two about making a React application feel like home for users across the globe. In this post, I'd like to share what I've learned.

What is internationalization?

Simply put, internationalization (sometimes shortened to i18n, where the 18 represents the number of characters between "i" and "n") refers to developing software in a way that enables localization.

Localization refers to adapting software to meet the language, cultural, and other requirements of a target market. This can include number, date, and time formatting, sorting considerations, translations, and more.

Dealing with Dates and Times

It's hard to overstate the importance of localizing dates and times. To a person from the US, 01/02/2022 means January 2nd, 2022. To someone from Australia, that would mean February 1st, 2022. In addition to differences in terms of layout, there are
differences in separators, different words, and different clock cycles that are used in different locales.

How could this become problematic? An example: a US-based company's web app tells global users that an important, action-required step needs to be taken by 01/02/2022. From a quick glance, a European or Australian user reads this as February 1st (instead of the intended January 2nd) and simply forgets about it until receiving notice in their email on January 3rd that they failed to perform the required steps by the deadline.

Try it!

Localizing dates used to be painful, and could involve generating different bundles for different locales, as the locale data was quite heavy in libraries like Moment, for example. Fortunately, according to CanIUse, browser support for Intl.DateTimeFormat is greater than 97% at the time of writing. This means that most applications should be able to leverage the browser's
date localization capabilities without needing to depend on heavy third-party dependencies.

The best way I've found to handle locale-aware date and time formatting is to create a simple component that leverages Intl.DateTimeFormat:

import React, { BaseHTMLAttributes} from 'react';

interface Props extends BaseHTMLAttributes<HTMLTimeElement>, Intl.DateTimeFormatOptions {
  fractionalSecondDigits?: 1 | 2 | 3;
  value?: string | number | Date;
  locale?: string;
}

const getDateString = (value: Props['value']): string | undefined => {
  if (!value) {
    return undefined;
  }

  try {
    const valueAsDate = new Date(value);

    return valueAsDate.toISOString();
  } catch {
    return undefined;
  }
};

const safelyFormatValue = (formatter: Intl.DateTimeFormat, value: Props['value']): string => {
  if (!value) {
    return '';
  }

  try {
    const dateFromValue = new Date(value);
    return formatter.format(dateFromValue);
  } catch {
    return '';
  }
};

export const FormatDate: React.FC<Props> = ({
  fractionalSecondDigits,
  hour,
  minute,
  day,
  month,
  year,
  second,
  value,
  timeZoneName,
  locale = 'default',
  ...rest
}) => {
  const dateFormatter = new Intl.DateTimeFormat(locale, {
    fractionalSecondDigits,
    hour,
    minute,
    day,
    month,
    year,
    second,
    timeZoneName,
  });

  return (
    // The dateTime attribute shows the ISO date being formatted with a quick DOM inspection
    <time dateTime={getDateString(value)} {...rest}>
      {safelyFormatValue(dateFormatter, value)}
    </time>
  );
};

The component code above was used for the date you see in the "Try it" section above. It is used like so:

<FormatDate day="2-digit" month="2-digit" year="numeric" value={new Date()} />

See the full documentation for more available options.

Relative Time

Many applications leverage relative times, for example, User commented 3 minutes ago or Livestream starting in 42 seconds. Fortunately for us, the browser offers a solution for this as well: Intl.RelativeTimeFormat.

Try it!

As with Intl.DateTimeFormat, I've found it easiest to create a simple component to leverage Intl.RelativeTimeFormat:

import React, { BaseHTMLAttributes} from 'react';

/**
* style is omitted from Intl.RelativeTimeFormatOptions and renamed to formatStyle to prevent a clash with the
* BaseHTMLAttributes "style" (which would be the CSS style object)
*/
interface Props extends BaseHTMLAttributes<HTMLSpanElement>, Omit<Intl.RelativeTimeFormatOptions, 'style'> {
  formatStyle?: Intl.RelativeTimeFormatStyle;
  unit: Intl.RelativeTimeFormatUnit;
  value: number;
  locale?: string;
}

export const FormatRelativeTime: React.FC<Props> = ({ formatStyle, locale = 'default', numeric, unit, value, ...rest }) => {
  const relativeTimeFormatter = new Intl.RelativeTimeFormat(locale, { style: formatStyle, numeric });

  return (
    // The unit and value data attributes make debugging easier with a quick DOM inspection
    <span data-unit={unit} data-value={value} {...rest}>
      {relativeTimeFormatter.format(value, unit)}
    </span>
  );
};

The component code above was used for the date you see in the "Try it" section above. It is used like so:

5 minutes ago

<FormatRelativeTime unit="minutes" value={-5}/>

In 10 seconds

<FormatRelativeTime unit="seconds" value={10}/>

See the full documentation for more available options.

Dealing with Numbers

Just as with dates, different locales handle number and currency formatting differently. For example, in the US, we use the comma
as the thousands separator (1,024) and the period as the decimal separator (3.14). In much of Europe, the period is used as the thousands separator (1.024) and the comma is used as the decimal separator (3,14). Intl.NumberFormat has excellent browser support and can deal with currency formatting, percentage formatting, various notations, and more.

Try it!

As with date and time formatting, I've found it easiest to create a simple component to leverage Intl.NumberFormat:

import React, { BaseHTMLAttributes } from 'react';

/**
* style is omitted from Intl.NumberFormatOptions and renamed to formatStyle to prevent a clash with the
* BaseHTMLAttributes "style" (which would be the CSS style object)
*/
interface Props extends BaseHTMLAttributes<HTMLSpanElement>, Omit<Intl.NumberFormatOptions, 'style'> {
  formatStyle?: string;
  locale?: string;
  value?: number;
}

export const FormatNumber: React.FC<Props> = ({
  currency,
  currencySign,
  useGrouping,
  minimumIntegerDigits,
  minimumFractionDigits,
  maximumFractionDigits,
  minimumSignificantDigits,
  maximumSignificantDigits,
  formatStyle,
  locale,
  value,
  ...rest
}) => {
  const numberFormatter = new Intl.NumberFormat(locale, {
    style: formatStyle,
    currency,
    currencySign,
    useGrouping,
    minimumIntegerDigits,
    minimumFractionDigits,
    maximumFractionDigits,
    minimumSignificantDigits,
    maximumSignificantDigits,
  });

  return (
    // The number data attribute makes debugging easier with a quick DOM inspection
    <span data-number={value?.toString()} {...rest}>
      {value === undefined || Number.isNaN(value) ? '' : numberFormatter.format(value)}
    </span>
  );
};

Note: if your application needs to support formatted cryptocurrency prices or values, Bitcoin is actually supported by the Intl.NumberFormat API with the currency code BTC, but many lesser known coin projects are not. Check out my post on working with currency values in TypeScript for a solution to that.

See the full documentation for more available options.

More from Intl

The Intl object has been under development in recent years, and there are several additional features worth exploring:

Intl.Collator is useful for language-sensitive string comparison (namely sorting). For example, this factors in diacritics and other characters (e.g., ö, á, ß, ж, ぉ).
Intl.ListFormat is useful for formatting groups of items into a string format. For example, German and several other languages do not use the Oxford comma, while English does.
Intl.PluralRules is useful for pluralizing items, as pluralization rules differ between locales. It can also be used for ordinal values (e.g., 1st, 3rd, 5th).
Intl.Segmenter is useful for splitting a string in a locale-sensitive manner. Did you know that there are languages (like Japanese, Chinese, and Thai) that don't use whitespace between words? This means that String.prototype.split(' ') will not actually provide an array of words in the sentence in these languages. Browser support for Intl.Segmenter is ok, but is notably missing Firefox support at the time of writing.

Note that some of this functionality can also be found in the i18n library I recommend in the next section.

Translation

As of 2022, there are 1.453 billion people in the world who speak English,
of which, only about 26% are native English speakers. With a global population of ~8 billion, that means only ~18% of the global population speaks English. There's a clear business case here for many applications to support additional languages.

Next, I'm going to break down how to serve and manage translations.

Serving Translations

While I believe there is a lot of valid criticism for using a library for everything in the JavaScript ecosystem, I strongly believe this is a case where you want to put your trust in the experts of the open-source community. The most common library I've seen for serving translations in a React app is react-i18next.

Initialize i18next

First, decide how you want to serve your translations. They can be bundled into your app's entrypoint bundle (probably not recommended), loaded as JSON via HTTP request from your public directory, or loaded via a third-party service. To get started, I would recommend serving from your public directory via the HTTP backend, but you can find a list of available backends here.

Next, install the dependencies (substituting in your preferred backend as applicable):

yarn add react-i18next i18next i18next-chained-backend i18next-http-backend i18next-localstorage-backend i18next-browser-languagedetector

i18n.ts

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import Backend from 'i18next-chained-backend';
import LocalStorageBackend from 'i18next-localstorage-backend';
import HTTPBackend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';

const backends = process.env.ENVIRONMENT === 'development'
    // in dev, always pull the latest translations, as they could be updating constantly
    ? [HTTPBackend]
    // in production, attempt to get locale storage-cached translations before hitting HTTP backend
    : [LocalStorageBackend, HTTPBackend];

i18n.use(Backend).use(LanguageDetector).use(initReactI18next).init({
    backend: {
      backends,
      backendOptions: [
        {
          prefix: '@@i18n_',
          expirationTime: 7 * 24 * 60 * 60 * 1000 * 7, // 1 week by default,
          store: window.sessionStorage,
          defaultVersion: process.env.CI_COMMIT_SHA, // This could be your app version
        },
        {
          loadPath: '/locales/{{lng}}/{{ns}}.json',
        },
      ],
    },
    supportedLngs: ['en-US', 'es-MX'],
    load: 'all',
    fallbackLng: 'en-US',
    ns: ['common'],
    defaultNS: 'common',
    interpolation: {
      escapeValue: false, // not needed for react, as it escapes by default
    },
});

export default i18n;

public/locales/en-US/common.json

{
  "greeting": "Hello {{name}}",
  "itemsToReview_one": "You have {{count}} item to review.",
  "itemsToReview_other": "You have {{count}} items to review.",
  "errors": {
    "userNotFound": "User not found",
    "urgentNotice": "<0>URGENT!</0> There was a problem. Click <1>here</1> for help."
  }
}

public/locales/es-MX/common.json

{
  "greeting": "Hola {{name}}",
  "itemsToReview_one": "Tienes {{count}} cosa que revisar.",
  "itemsToReview_other": "Tienes {{count}} cosas que revisar.",
  "errors": {
    "userNotFound": "Usuario no encontrado",
    "urgentNotice": "<0>¡Urgente!</0> Había un problema. Haga clic <1>aquí</1> para obtener ayuda."
  }
}

The next step is to import your i18n instance into your app's entry point (index.tsx or the like):

import './i18n';

Once this is done, you can start using the useTranslation() hook to replace hard-coded strings with translated ones:

import { useTranslation, Trans } from 'react-i18next';

interface Props {
  error: any;
  itemsToReview: number;
  name: string | undefined;
}

export const Greeting: React.FC<Props> = ({ error, itemsToReview, name }) => {
  const { t } = useTranslation('common');

  if (error) {
    return (
      <div>
        <Trans t={t} i18nKey="common:errors.urgentNotice">
          <strong />
          <a href="/support" />
        </Trans>

        <p>{t('common:errors.userNotFound')}</p>
      </div>
    );
  }

  return (
    <div>
      <span>{t('common:greeting', { name })}</span>
      <span>{t('common:itemsToReview', { count: itemsToReview })}</span>
    </div>
  );
};

In the example above, you can see examples of a few of the key react-i18next concepts:

common, passed to useTranslation() and prepended in the i18nKey is the namespace. In order for i18next to load a namespace from your configured backend, you need to pass it to useTranslation(), which can take an array of namespaces. Keys are always prefixed with their namespace, which by default matches the filename before .json of the file that the translation is located in.
t, returned by useTranslation() is the function that handles translating simple strings that don't require interpolation. The first argument is the i18nKey and the second is the variable object required for the key. You can also see an example of a key, common:itemsToReview, which has different pluralization rules depending on the count. Note that some languages have more complicated pluralization rules than English.
<Trans /> is used to interpolate more complex items into your translations (like React Elements). In this case, it's used to translate the support link as part of a full phrase.

I like to use an abstraction component over react-i18next to help with debugging translation issues with peers across the business.

import React, { BaseHTMLAttributes, Suspense } from 'react';
import { Trans, useTranslation } from 'react-i18next';

interface Props extends BaseHTMLAttributes<HTMLSpanElement> {
  element?:
    | 'span'
    | 'b'
    | 'strong'
    | 'em'
    | 'p'
    | 'h1'
    | 'h2'
    | 'h3'
    | 'h4'
    | 'h5'
    | 'h6';
  i18nKey: string;
  variables?: Record<string, any>;
}

const useTranslationProps = ({
  children,
  i18nKey,
  variables,
  ...rest
}: Omit<Props, 'element'>) => {
  const namespace = i18nKey.split(':')[0];
  const { t } = useTranslation(namespace);

  return {
    ...rest,
    'data-i18n-key': i18nKey,
    'children': children ? (
      <Trans t={t} i18nKey={i18nKey} values={variables}>
        {children}
      </Trans>
    ) : (
      t(i18nKey, variables)
    ),
  };
};

const TextInner: React.FC<Props> = ({ element = 'span', ...rest }) => {
  const props = useTranslationProps(rest);

  switch (element) {
    case 'b':
      return <b {...props} />;
    case 'strong':
      return <strong {...props} />;
    case 'em':
      return <em {...props} />;
    case 'p':
      return <p {...props} />;
    case 'h1':
      return <h1 {...props} />;
    case 'h2':
      return <h2 {...props} />;
    case 'h3':
      return <h3 {...props} />;
    case 'h4':
      return <h4 {...props} />;
    case 'h5':
      return <h5 {...props} />;
    case 'h6':
      return <h6 {...props} />;
    case 'span':
    default:
      return <span {...props} />;
  }
};

export const Text: React.FC<Props> = (props) => (
  // I would recommend having a higher-level Suspense with a loading spinner fallback
  <Suspense fallback="[...]">
    <TextInner {...props} />
  </Suspense>
);

What this accomplishes is:

It gives you a consistent interface to add translated text to your interface, regardless of interpolation.
It adds the data-i18n-key data attribute to your translated text in the DOM, so your peers across the business can quickly point you to the translation key that is causing trouble, regardless of which language they're using the application in.
It ensures that the required namespaces are loaded into your application.

Simple example using key from above

<Text i18nKey="common:greeting" variables={{name}}/>

Example with interpolation using key from above

<Text i18nKey="common:errors.urgentNotice">
    <strong/>
    <a href="/support"/>
</Text>

Update the `html` Tag with the Appropriate `lang` Attribute

It's important to update your application's html tag with the appropriate lang attribute, because it gives context to screen readers and other assistive technologies. Here's a sample hook that does just that:

import { useEffect } from 'react';
import { useTranslation } from 'react-18next';

export const useUpdateHTMLLanguage = () => {
  const { i18n } = useTranslation();

  useEffect(() => {
    document.documentElement.setAttribute('lang', i18n.resolvedLanguage);
  }, [i18n.resolvedLanguage]);
}

Translation Management

While actually having the translations written in various locales is not likely in scope for an engineering team, I'll share what I've seen work.

The engineering team should commit to adding new translation keys for one locale. In this case, let's assume en-US for the sake of this example. As the engineers are working, they will add copy to the locales/en-US.json file and carry on with their work. When they open a pull request for their work upstream to their development environment, a script can run in CI that will check for newly-created keys that aren't present in all the supported locales and notify the appropriate translators that your branch needs translation work. Alternatively, you could consider a tool like translation-check, which will create a simple dashboard where you can get an overview of missing translations by locale.

There are also a number of third-party services that offer translation management and collaboration dashboards (Locize, Loco, Lokalise, etc.).

Layout Shifting

It's worth noting that many times, layouts are only designed with the default language in mind, which is oftentimes English. There are a number of languages that can be more verbose than English. For example, Spanish, Portuguese, and Russian are often more space-consuming than English and can cause overflow issues for your application. Unfortunately, there's not a great way to prevent this. I would recommend naming your translation keys in a manner that is self-explanatory to the translators to ensure they have space constraints in-mind when crafting their translations.

I haven't found a great automated tool for testing overflow, but I would recommend manually testing translation additions in all languages as part of your pre-release process. Of course, the most important areas to focus on will depend on your application, but I have often seen issues with navigation overflow in both headers and footers. The layout elements are the lowest-hanging fruits.

Right-to-Left (RTL)

While the majority of languages are written from left-to-right (LTR), there are a few prominent languages that are written from right-to-left (e.g., Arabic and Hebrew). I have not yet had to work on an application that had business requirements to support RTL, but from what I understand, there are a few key concepts to keep in mind.

Update the `html` Tag with the Appropriate `dir` Attribute

The dir attribute in the page's html tag should be set to rtl for right-to-left languages, otherwise ltr, auto, or unset.

Here's a sample hook that does just that:

import { useEffect } from 'react';
import { useTranslation } from 'react-18next';

export const useUpdateHTMLDirection = () => {
  const { i18n } = useTranslation();
  const dir = i18n.dir(); // Where dir will be 'ltr' or 'rtl';

  useEffect(() => {
    document.documentElement.setAttribute('dir', dir);
  }, [dir]);
}

Note that this could be combined with the hook to update the language on the html tag as well.

You can also use the dir attribute on structural elements throughout your page if only parts of your application need to read from right-to-left.

Flip the Layout

The "F" layout that many websites use is great for languages that read from left-to-right, but it should be flipped for your users that are reading your website from right-to-left. This can be accomplished without much effort if you use flexbox or grid-based layouts. For example:

.flex-layout {
  display: flex;
  flex-direction: row;
}

.grid-layout {
  display: grid;
  grid-template-columns: 320px 1fr;
}

[dir="rtl"] .flex-layout {
  flex-direction: row-reverse;
}

[dir="rtl"] .grid-layout {
  grid-template-columns: 1fr 320px;
}

Realign the Text

For right-to-left languages, you will likely want to flip the text alignment you have in your standard left-to-right template to better match the flipped layout. You can accomplish this fairly easily by making the following replacements:

.align-start {
  // text-align: left; Before
  text-align: start; // After
}

.align-end {
  // text-align: right; Before
  text-align: end; // After
}

Fix Spacing

Instead of using hard *-left and *-right spacing values (margin and padding), you will want to use the following
replacements that take writing directionality in mind:

padding-inline-start in place of padding-left
padding-inline-end in place of padding-right
margin-inline-start in place of margin-left
margin-inline-end in place of margin-right

Conclusion

While the diversity in culture, tradition, and language are some of the things that make the world so beautiful, they can cause unsuspecting engineers a lot of trouble. It would be unrealistic to expect any single engineer, or even team, to hold all the information required to internationalize an application manually. Fortunately, it has never been easier to internationalize and localize an application than it is today with Intl reaching great browser support and developing rapidly. If you think there's something I missed or got wrong, reach out to me on Twitter and share @joshuaslate.

Working with Currency Values in TypeScript

Joshua Slate — Thu, 01 Dec 2022 14:01:16 +0000

Having spent the past few years working for FinTech companies, I have had to work with currency values a lot. I've learned some convenient patterns for working with formatting currency values. In this post, I'm going to break down some of my favorite patterns, and lessons I learned the hard way, so you don't need to.

Formatting and Localization

As mentioned in my previous post about internationalization, it is important for software engineers to localize their software so that their users are receiving information in the way they best understand. As it relates to numbers, there are a variety of formats used by different locales. For example, in the US, we would format one-thousand-two-hundred-thirty-four dollars and 56 cents like so: $1,234.56. In Germany, that would be 1.234,56 $. In Mexico, it would be USD 1,234.56.

Getting Started

The cornerstone of our currency formatting will be Intl.NumberFormat. Browser support for Intl.NumberFormat is in great shape at this point, with more than 97% of global Internet users using browsers that support it.

Creating an Intl.NumberFormat formatter is quite simple:

const formatter = new Intl.NumberFormat('default', {
  style: 'currency',
  currency: 'USD',
});

// Try replacing 'default' with various locales like 'en-US', 'de-DE', 'ar-EG', and 'zh-CN', for example.
formatter.format(1234.56);

There are additional options available that you can view here.

Try it!

Unsupported Currencies

While working on various financial applications, I learned that if you pass an unsupported currency (many cryptocurrencies, for example) to the Intl.NumberFormat constructor, it will throw an error. Using the fictional REACT coin as an example, the following error would be thrown: RangeError: Invalid currency code : REACT.

One way I've worked around this is by first attempting to instantiate an Intl.NumberFormat with the provided options, then falling back to Bitcoin (BTC) formatting if the selected currency is unsupported.

An example:

const getNoOpFormatter = (
  locale: string = 'default',
  options?: Intl.NumberFormatOptions
) => ({
  format: (x: number | bigint | undefined) => x?.toString() || '',
  formatToParts: (x: number | bigint | undefined) => [
    { type: 'unknown' as Intl.NumberFormatPartTypes, value: x?.toString() || '' }
  ],
  resolvedOptions: new Intl.NumberFormat(locale, options).resolvedOptions
});

export const getCurrencyFormatter = (
  locale: string = 'default',
  options?: Intl.NumberFormatOptions
): Intl.NumberFormat => {
  try {
    return new Intl.NumberFormat(locale, options);
  } catch {
    if (options?.style === 'currency' && options?.currency) {
      const rootFormatter = new Intl.NumberFormat(locale, {
        ...options,
        currency: 'BTC'
      });

      return {
        format: (x: number | bigint | undefined) =>
          rootFormatter
            .formatToParts(x)
            .map((part) =>
              part.type === 'currency' ? options.currency : part.value
            )
            .join(''),
        formatToParts: (x: number | bigint | undefined) =>
          rootFormatter.formatToParts(x).map((part) =>
            part.type === 'currency'
              ? ({
                  ...part,
                  value: options.currency
                } as Intl.NumberFormatPart)
              : part
          ),
        resolvedOptions: rootFormatter.resolvedOptions
      };
    }

    return getNoOpFormatter(locale, options);
  }
};

There is, however, a pitfall to this approach. It defaults to 2 maximumFractionDigits. Depending on your currency, this may or may not be enough. You would need to override that option to provide sufficient fractional digits.

Arithmetic and Comparison Operations

String Values for Arithmetic

As concepts like fractional share ownership and cryptocurrency continue to materialize and expand across the global economy,
JavaScript applications will have an increasingly difficult time in dealing with numbers due primarily to two issues:

Floating point precision: computations on floating point numbers aren't necessarily deterministic and produce incorrect results.

0.1 + 0.2 === 0.3; // false 🤯 try it in your browser console. I get: 0.30000000000000004

Numbers greater than {Number.MAX_SAFE_INTEGER} and less than {Number.MIN_SAFE_INTEGER} are out of range and produce incorrect values when exceeded in either direction when performing arithmetic operations.

For financial applications, APIs commonly return currency values, balances, stock/currency positions, and other amounts as strings. The best way I've found to deal with this is to use a library like big.js.

Using a library like big.js, you are able to convert the string number values to Big objects, which can safely perform arithmetic and comparison operations. For example:

import Big from 'big.js';

new Big(Number.MAX_SAFE_INTEGER).times(5).toString() === '45035996273704955'; // true
new Big(Number.MIN_SAFE_INTEGER).times(5).toString() === '-45035996273704955'; // true
new Big(0.1).add(0.2).eq(0.3); // true

As you can see, the issues we were facing with JavaScript's number primitive are solved by using big.js. However, this presents another issue for us. We have two main methods for getting a usable primitive value out of our Big object: toString() and toNumber().

Here's where things get interesting again.

Intl.NumberFormat.prototype.format() has great browser support when you're passing it a number or bigint value, but string number values are not yet well-supported and are considered experimental at the time of writing. Anecdotally, passing string number values seems to be working for me in the latest builds of Chrome, Firefox, and even Safari. With this in mind, using the value returned from Big.prototype.toString() might work. Let's consider our other option.

Big.prototype.toNumber() will return a JavaScript number primitive, but it's possible that precision will be lost. According to the documentation, you can set Big.strict = true;, which will cause Big.prototype.toNumber() to throw if it's called with a number that cannot be converted to primitive number without precision loss. Depending on the size of numbers in your application, this might be acceptable.

It seems like we're left with two solutions that kind of get the job done in certain situations, but I think we can take it a step further.

import Big from 'big.js';

/**
 * Note that in strict mode, you'll need to pass string or bigint 
 * values as the BigSource for various Big methods and the
 * constructor
*/
Big.strict = true;

const safelyFormatNumberWithFallback = (formatter: Intl.NumberFormat, value: Big) => {
  // First, attempt to format the Big as a number primitive
  try {
    return formatter.format(value.toNumber());
  } catch {}

  // Second, attempt to format the Big as a string primitive
  try {
    return formatter.format(value.toString());
  } catch {}

  // As a fallback, simply return the ugly string value
  return value.toString();
}

Bonus: Putting it All Together in a React Component

import React, { BaseHTMLAttributes, useMemo } from 'react';
import Big from 'big.js';
import { getCurrencyFormatter, safelyFormatNumberWithFallback } from '../helpers/number'; // The functions from above

interface Props extends BaseHTMLAttributes<HTMLSpanElement>, Omit<Intl.NumberFormatOptions, 'style'> {
  locale?: string;
  value?: Big;
}

export const FormatCurrencyValue: React.FC<Props> = ({
  currency = 'USD',
  currencySign,
  useGrouping,
  minimumIntegerDigits,
  minimumFractionDigits,
  maximumFractionDigits,
  minimumSignificantDigits,
  maximumSignificantDigits,
  locale = 'default',
  value,
  ...rest
}) => {
  const numberFormatter: Intl.NumberFormat = useMemo(
    () => getCurrencyFormatter(locale, {
      currency,
      currencySign,
      useGrouping,
      minimumIntegerDigits,
      minimumFractionDigits,
      maximumFractionDigits,
      minimumSignificantDigits,
      maximumSignificantDigits,
    }),
    [
      locale,
      currency,
      currencySign,
      useGrouping,
      minimumIntegerDigits,
      minimumFractionDigits,
      maximumFractionDigits,
      minimumSignificantDigits,
      maximumSignificantDigits,
    ],
  );

  return (
    // I find it helpful to pass the raw value data attribute down to make debugging easier from a quick DOM inspection
    <span data-value={value?.toString()} {...rest}>
      {safelyFormatNumberWithFallback(numberFormatter, value)}
    </span>
  );
}

Parting Shot

I would like to close this post with an opinion: currency values (or just numeric values in general) are best rendered in a monospace font. They allow users to scan through data more quickly and accurately.

As always, if I missed something or made a mistake, please reach out to me on Twitter. If you learned something, don't hesitate to share.

Forem: Joshua Slate

Deterministic React Avatar Fallbacks

Building the Base Avatar Component

Implementing Gravatar

Deterministically Personalizing Avatar Colors

Putting It All Together

Try it!

Internationalizing and Localizing a React App: i18n Made Easy

What is internationalization?

Dealing with Dates and Times

Try it!

Relative Time

Try it!

Dealing with Numbers

Try it!

More from Intl

Translation

Serving Translations

Initialize i18next

Update the html Tag with the Appropriate lang Attribute

Translation Management

Layout Shifting

Right-to-Left (RTL)

Update the html Tag with the Appropriate dir Attribute

Flip the Layout

Realign the Text

Fix Spacing

Further Reading: Vertical Writing

Conclusion

Working with Currency Values in TypeScript

Formatting and Localization

Getting Started

Try it!

Unsupported Currencies

Arithmetic and Comparison Operations

String Values for Arithmetic

Bonus: Putting it All Together in a React Component

Parting Shot

Update the `html` Tag with the Appropriate `lang` Attribute

Update the `html` Tag with the Appropriate `dir` Attribute