Translate UI text

[tesseralis]

Summary

Extract all English text in components to YAML translation files.

Motivation

We need to factor out English text into yaml files so that we can translate them.

Implementation

1. Extract all text to YAML files, and put them somewhere the update-source script can find easily and copy over to gatsby-i18n-source
2. Source this YAML directory in gatsby-config
3. Either:
   a) pull in this content directly via GraphQL or
   b) use an i18n library like react-intl or react-i18next and provide all the translations via a context provider.

Details

I think the best way to go about this given the considerations above is to put UI text in a top-level directory in the monorepo, with files (or subdirectories if they get too large) for each section.

docs/
  ...
ui-text/
  navigation.yaml
  footer-links.yaml
  prev-and-next.yaml
www/
  ...

Each file should be a list of key-value pairs (e.g navigation.yaml):

navAriaLabel: Primary Navigation
searchPlaceholder: Search gatsbyjs.org
searchAriaLabel: Search gatsbyjs.org
searchTitle: Press 's' to search docs

We should source this top-level directory in gatsby-config. We can then source this YAML in the components that need them using GraphQL.

When we have translated versions or move packages to their own repository, we may want to consider using an i18n library that uses a context provider and hook up all the translations at the top-level, similarly to how theme-ui works.

Core Components

These components should be handled first, since they appear on (nearly) every page in Gatsby or pages in the "core docs" to translate

• navigation.js: section names
  • search-form.js: search text placeholder/aria attributes
• footer-links.js: link names
• prev-and-next.js: "Previous"/"Next"
• sidebar/button-expand-all.js: "Expand All" / "Collapse All"
• feedback-widget.js - we're not going to show this in non-English sites since we have no way to process it right now
• markdown-page-footer.js: "Edit this page on GitHub"
• docs-table-of-contents.js: "Table of Contents"
• skip-nav-link.js
• copy.js - used in code blocks

These components also appear on multiple pages:

• email-capture-form.js
• guide-list.js: "In this section"
• layer-model.js

Open Questions

• Should we treat things like navigation specially? e.g. the list of navigation items or the currently existing sidebar yaml file.
  • The sidebar contents can be taken from the docs; everything else is treated normally.
• What i18n library should we use?
  • We are using react-intl

[github-actions]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[github-actions]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.
Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks again for being part of the Gatsby community! 💪💜

[tesseralis]

I took the liberty of researching a couple of translation libraries and their associated gatsby plugins, since we have some instances of rich text (for example here and here) that could benefit from a dedicated i18n library. Results have been... mixed so far, so I figure I'd write down my thoughts on the matter for now.

react-i18next

It's not very declarative. You initialize it by calling a bunch of functions on global constants instead of passing a value to a provider. Their rich text formatting is kind of wonky: you do it by surrounding stuff you want to format in numbered XML tags (e.g. this text is <1>bold<1>, and it doesn't really provide a good solution for how to do it.

gatsby-plugin-i18next

It's not a very well-maintained plugin and doesn't have clear instructions on how to use it. It uses an old version that doesn't have hooks, and it has a lot of forks that purport to have hotfixes, which doesn't bode well for its maintenance status.

It does do something interesting though: it's able to store key-value pairs in GraphQL without having to [request all the keys] by creating a child node of the language files that store the data as stringified JSON, which the plugin then parses later. This is something we might consider doing.

react-intl

So far I like it better than the react-i18next. You initialize it by passing props to a [provider], completely declaratively. Its rich text formatting is more manageable: you can define your own XML nodes and what components to pass to them (however, I haven't managed to get it to work with SSR). The only downside compared to i18next that getting the translation strings is more verbose (formatMessage({ id: 'messageId' }) instead of t('messageId')).

gatsby-plugin-intl

AHHHH. This plugin almost has everything we need. It creates pages for each locale for you, has a localized Link components, and takes care of setting up everything react-intl related. But there are a few issues:

• The way it creates localized pages doesn't transfer page context. The translated versions of the homepage complained that it couldn't find one of the query variables. Given how big the gatsby site is and how it has thousands of pages, it might not be beneficial to generate localized pages for everything all at once.
• It's Link component doesn't handle the case where a link is already localized: having <Link to={location.pathname + hash}/> makes es/tutorial#part-one go to es/es/tutorial#part-one.
• It requires config to be in local JSON files, and doesn't support external sources. I'm actually okay with this. The only reason the markdown files are in separate repos is because there's too many of them. But there are a lot less UI text strings and they shouldn't be edited that often. It also simplifies a lot of [issues regarding integration] to keep them in the same repo.

---

I think the best thing would be if I can get react-intl to work with rich text formatting. Otherwise... I'm not quite sure what we should do.