Room UI Redesign: Auth Localization #3555

robertlong · 2020-12-14T18:38:18Z

This is the first of the localization PRs. I'm going to split them up into chunks around the same size as this throughout the week. This first PR covers the authentication components, including sign-in modal messages used throughout the client.

I'm establishing a slightly new workflow and a few best practices for localization based off the react-intl documentation, a blog post by the team at Calm, and the work needed to integrate with Mozilla Pontoon.

The new workflow will rely on react-intl's CLI tool for message extraction. We will define an id, a default message, and optionally a description as we already do with the <FormattedMessage> component or with the defineMessage() method. This data will be extracted along with the file path and line numbers and it will be fed into Pontoon. From there, Pontoon will be used to generate translation files. Which will be committed back to the Hubs repository by Pontoon's bot. These files will be in a new format from the existing files. At build time we will translate them into the react-intl compatible files.

The best practices for localization are the following:

1. Message ids cannot contain variables.

This is due to the message extraction relying on static code analysis.

Example:

import { FormattedMessage, defineMessages, useIntl } from "react-intl";

// Good
<FormattedMessage id="sign-in-modal.complete" defaultMessage="Sign in complete" />

// Bad
<FormattedMessage id={`sign-in-modal.${step}`} />

// Good
const messages = defineMessages({
  prompt: {
    id: "sign-in-modal.prompt",
    defaultMessage: "Please sign in"
  },
  complete: {
    id: "sign-in-modal.complete",
    defaultMessage: "Sign in complete"
  }
});

function SignInModal({ step }) {
  const intl = useIntl();

  return <p>{intl.formatMessage(messages[step])}</p>;
}

// Bad
function SignInModal({ step }) {
  return <p><FormattedMessage id={`sign-in-modal.${step}`} /></p>;
}

2. Message ids should be namespaced with the component/parent component name.

We are not using auto-generated ids due to backwards-compatibility issues with our existing translations. As such, we need to ensure that there are no collisions. Name the translation ids by starting with the component name in dash/kebab case. If the component is split up into multiple local components and is only used in the context of a parent component, use the parent component name.

Example:

// Good
function SignInModal() {
 return <FormattedMessage id="sign-in-modal.complete" defaultMessage="Sign in complete" />;
}

// Bad
function SignInModal() {
 return <FormattedMessage id="sign-in.complete" defaultMessage="Sign in complete" />;
}

// Good
function ObjectListItem({ item }) {
 return (
  <li>
    {item.name}
    <button>
      <FormattedMessage id="object-list.select" defaultMessage="Select Object" />
    </button>
  </li>
  );
}

export function ObjectList({ objects }) {
 return <ul>{objects.map(o => <ObjectListItem item={o} />)}</ul>;
}

3. Always specify a default message.

Default messages will be used to provide context to translators, they are the fallback message if it is not defined for another language, and they are used as the English translation by default.

// Good
<FormattedMessage id="sign-in-modal.complete" defaultMessage="Sign in complete" />

// Bad
<FormattedMessage id={`sign-in-modal.complete`} />

// Good
const signInCompleteMessage = defineMessage({
  id: "sign-in-modal.complete",
  defaultMessage: "Sign in complete"
});

// Bad
const signInCompleteMessage = defineMessage({
  id: "sign-in-modal.complete"
});

4. All strings presented to users should be localized including accessibility features

It is not enough to localize just the visible text. All labels, alt text, and callouts should also be localized.

<img alt={<FormattedMessage id="logo.alt-text" defaultMessage="Hubs Logo" />} src="logo.png" />

<div aria-label={<FormattedMessage id="element.label" defaultMessage="This is a label" />}></div>

<div title={<FormattedMessage id="element.title" defaultMessage="This is a title" />}></div>

5. Use react-intl's formatter for formatting concatenated strings.

Different languages have different grammatical rules and sentence structure. Relying on string concatenation that works in English will not always make sense in another language. Use react-intl's values prop to format messages with variables or rich formatting. If formatting gets too complicated break it up into multiple messages.

// Bad
<p>
  <small>
    By proceeding, you agree to the{" "}
    {showTerms && (
      <>
        <a rel="noopener noreferrer" target="_blank" href={termsUrl}>
          terms of use
        </a>{" "}
      </>
    )}
    {showTerms && showPrivacy && "and "}
    {showPrivacy && (
      <a rel="noopener noreferrer" target="_blank" href={privacyUrl}>
        privacy notice
      </a>
    )}.
  </small>
</p>

// Good
export function LegalMessage({ termsUrl, privacyUrl }) {
  const toslink = useCallback(
    chunks => (
      <a rel="noopener noreferrer" target="_blank" href={termsUrl}>
        {chunks}
      </a>
    ),
    [termsUrl]
  );

  const privacylink = useCallback(
    chunks => (
      <a rel="noopener noreferrer" target="_blank" href={privacyUrl}>
        {chunks}
      </a>
    ),
    [privacyUrl]
  );

  if (termsUrl && privacyUrl) {
    return (
      <FormattedMessage
        id="legal-message.tos-and-privacy"
        defaultMessage="By proceeding, you agree to the <toslink>terms of use</toslink> and <privacylink>privacy notice</privacylink>."
        values={{
          toslink,
          privacylink
        }}
      />
    );
  }

  if (termsUrl && !privacyUrl) {
    return (
      <FormattedMessage
        id="legal-message.tos"
        defaultMessage="By proceeding, you agree to the <toslink>terms of use</toslink>."
        values={{
          toslink
        }}
      />
    );
  }

  if (!termsUrl && privacyUrl) {
    return (
      <FormattedMessage
        id="legal-message.privacy"
        defaultMessage="By proceeding, you agree to the <privacylink>privacy notice</privacylink>."
        values={{
          privacylink
        }}
      />
    );
  }

  return null;
}

Reference messages as objects or defineMessages keys, not ids
Message objects contain an id and a default message. Pass the whole object into a component and use intl.formatMessage to render it. Alternately, use a defineMessages function to define messages with keys and use that key to reference the message.

const errorMessages = defineMessages({
  unknown: {
    id: "error-message.unknown",
    defaultMessage: "An unknown error occured"
  },
  notFound: {
    id: "error-message.not-found",
    defaultMessage: "Page not found"
  }
});

// Good
function ErrorMessage({ message }) {
  const intl = useIntl();

  return <code>{intl.formatMessage(message)}</code>
}

<ErrorMessage message={errorMessages.unknown} />

// Good
function ErrorMessage({ type }) {
  const intl = useIntl();

  return <code>{intl.formatMessage(errorMessages[type])}</code>
}

<ErrorMessage type="unknown" />

I've installed Calm's linter rules that will check for some of these issues. Right now we are failing a lot of those rules and there are a lot of warnings. I'll work through these issues throughout the week in separate PRs until they are corrected. Once they are corrected I will switch the linter to throw errors rather than warn.

robinkwilson

A few small things. Looks good. So excited for this localization linter update!

robinkwilson · 2020-12-14T23:22:13Z

src/assets/locales/README.md

+// Good
+export function LegalMessage({ termsUrl, privacyUrl }) {
+  const toslink = useCallback(


Suggested change

const toslink = useCallback(

const tosLink = useCallback(

I think the capitalization here is correct as lowercase since it's being used as an HTML element name.

Notice how it's used here:

<FormattedMessage id="legal-message.privacy" defaultMessage="By proceeding, you agree to the <privacylink>privacy notice</privacylink>." values={{ privacylink }} />

robinkwilson · 2020-12-14T23:22:38Z

src/assets/locales/README.md

+  );
+
+  const privacylink = useCallback(


Suggested change

const privacylink = useCallback(

const privacyLink = useCallback(

robinkwilson · 2020-12-14T23:25:31Z

src/react-components/auth/LegalMessage.js

+import { FormattedMessage } from "react-intl";
+
+export function LegalMessage({ termsUrl, privacyUrl }) {
+  const toslink = useCallback(


Suggested change

const toslink = useCallback(

const tosLink = useCallback(

robinkwilson · 2020-12-14T23:25:48Z

src/react-components/auth/LegalMessage.js

+    [termsUrl]
+  );
+
+  const privacylink = useCallback(


Suggested change

const privacylink = useCallback(

const privacyLink = useCallback(

robinkwilson · 2020-12-14T23:26:05Z

src/react-components/auth/LegalMessage.js

+        id="legal-message.tos-and-privacy"
+        defaultMessage="By proceeding, you agree to the <toslink>terms of use</toslink> and <privacylink>privacy notice</privacylink>."
+        values={{
+          toslink,


Suggested change

toslink,

tosLink,

robinkwilson · 2020-12-15T02:52:47Z

src/react-components/link-root.js

-                  }
-                />
+                {this.state.failedAtLeastOnce ? (
+                  <FormattedMessage id="link.try_again" />


Should this be link-root.try_again since the component is called LinkRoot?

Suggested change

<FormattedMessage id="link.try_again" />

<FormattedMessage id="link-root.try_again" />

I did all of the non-auth component changes just to get tests to pass, but yeah I need to come back and fix these.

robinkwilson · 2020-12-15T02:53:15Z

src/react-components/link-root.js

+                {this.state.failedAtLeastOnce ? (
+                  <FormattedMessage id="link.try_again" />
+                ) : this.state.isAlphaMode ? (
+                  <FormattedMessage id="link.link_page_header_headset" />


Suggested change

<FormattedMessage id="link.link_page_header_headset" />

<FormattedMessage id="link-root.link_page_header_headset" />

robinkwilson · 2020-12-15T02:53:28Z

src/react-components/link-root.js

+                ) : this.state.isAlphaMode ? (
+                  <FormattedMessage id="link.link_page_header_headset" />
+                ) : (
+                  <FormattedMessage id="link.link_page_header_entry" />


Suggested change

<FormattedMessage id="link.link_page_header_entry" />

<FormattedMessage id="link-root.link_page_header_entry" />

robinkwilson · 2020-12-15T02:59:08Z

src/react-components/room/TipContainer.js

 import { Tip } from "./Tip";
 import { useEffect } from "react";
 import { discordBridgesForPresences, hasEmbedPresences } from "../../utils/phoenix-utils";

+const onboardingMessages = defineMessages({
+  "tips.mobile.look": {
+    id: "tips.mobile.look",


Should all of these be tip-container rather than tips ?

Suggested change

id: "tips.mobile.look",

id: "tip-container.mobile.look",

robinkwilson · 2020-12-15T03:06:09Z

src/react-components/auth/SignInModal.js

-export function SubmitEmail({ onSubmitEmail, initialEmail, showPrivacy, privacyUrl, showTerms, termsUrl, message }) {
+export const SignInMessages = defineMessages({
+  pin: {
+    id: "sign-in.pin",


Should these be sign-in-modal (and update the en.json, etc)? I believe this is your exact example in the documentation.

Suggested change

id: "sign-in.pin",

id: "sign-in-modal.pin",

Yup 😅 I meant to come back and fix this, thanks for catching it!

robertlong added 3 commits December 14, 2020 10:37

Add localization for auth components

f7a5e15

Lint warnings

c1797ce

Add best practices guide to localization docs

2ffc1a6

robertlong requested review from johnshaughnessy and robinkwilson December 14, 2020 20:52

robertlong added 2 commits December 14, 2020 13:23

Fix broken paths

559fc97

Make tests pass by removing all variables in react-intl ids

463879d

robinkwilson reviewed Dec 15, 2020

View reviewed changes

Fix up auth translation ids

30783fe

robertlong merged commit 180161f into room-ui-redesign Dec 15, 2020

robertlong deleted the redesign/auth-localization branch December 15, 2020 21:08

johnshaughnessy mentioned this pull request Mar 5, 2021

April 2021 Hubs Cloud Update #3988

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Room UI Redesign: Auth Localization #3555

Room UI Redesign: Auth Localization #3555

robertlong commented Dec 14, 2020 •

edited

Loading

robinkwilson left a comment

robinkwilson Dec 14, 2020

robertlong Dec 15, 2020

robinkwilson Dec 14, 2020

robinkwilson Dec 14, 2020

robinkwilson Dec 14, 2020

robinkwilson Dec 14, 2020

robinkwilson Dec 15, 2020

robertlong Dec 15, 2020

robinkwilson Dec 15, 2020

robinkwilson Dec 15, 2020

robinkwilson Dec 15, 2020

robinkwilson Dec 15, 2020

robertlong Dec 15, 2020

	const privacylink = useCallback(
	const privacyLink = useCallback(

	<FormattedMessage id="link.try_again" />
	<FormattedMessage id="link-root.try_again" />

	<FormattedMessage id="link.link_page_header_headset" />
	<FormattedMessage id="link-root.link_page_header_headset" />

Room UI Redesign: Auth Localization #3555

Room UI Redesign: Auth Localization #3555

Conversation

robertlong commented Dec 14, 2020 • edited Loading

1. Message ids cannot contain variables.

2. Message ids should be namespaced with the component/parent component name.

3. Always specify a default message.

4. All strings presented to users should be localized including accessibility features

5. Use react-intl's formatter for formatting concatenated strings.

robinkwilson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

robertlong commented Dec 14, 2020 •

edited

Loading