Product Guide

ReadMe Documentation

Welcome to the ReadMe Documentation, where you'll find comprehensive guides and community support to help you start working with ReadMe as quickly as possible!

Get Started

Language Support/Localization

Introduction

ReadMe is proud to provide integrations with two power localization services, Localize and Transifex. Integration is simple, and gives you access to many translation tools, including:

  • Automatically detect changes to phrases in your docs project.
  • Let your teams collaborate on translation and publication of those phrases.
  • In-context editors.
  • The ability to select what parts of a page to translate at the string level.
  • Automatically provide a language picker for your users.
  • Machine translation with human oversight, or easy outsourcing to human translators.
  • Auto-translation of saved phrases.

ReadMe offers a particularly deep integration with Transifex:

  • An out-of-the-box search experience for end users in multiple languages. (ReadMe does this by using Transifex's API to build search index(es) of translated phrases.)
  • ReadMe improves on Transifex's default search engine optimization (SEO) for translated content. To avoid any dings to your SEO, ReadMe prerenders translated strings so that search engines can "see" and rank the translations.

📘

Enterprise Only

Integration with Transifex is an enterprise feature only. Contact [email protected] if you are interested!

Note that If you don't want to pay for Transifex or Localize, you could create a bare-bones translation with the following steps:

  • Clone your documentation project into a new project.
  • Manually replace the existing content in the new project with translated content in the ReadMe online editor.
  • Set up site navigation in your project dashes for users to switch between your doc projects.

This approach is best for very small projects, and entails very high content management overhead.

Sample Localized Docs

For examples of ReadMe docs localized with Transifex, see:

Localize Integration

Even if you're not a developer, it's fairly simple to integrate Localize with your docs:

  1. Sign up for an account at Localize.

  2. In your ReadMe dash, go to General Settings > Integrations, where you can paste in a Localize API key.
    For more information about the API key, read their documentation specific to ReadMe.

  3. After you integrate with Localize, you still need to push each documentation page to Localize. To do so, refresh or revisit the page you want to translate in your browser. Then, you can manage and publish translations of that page in Localize's online app. Localize automatically adds a language picker menu in the lower right of your docs site for your users:

LocalizeJS language picker.

Transifex Integration

Even if you're not a developer, it's fairly simple to integrate Transifex with your docs:

  1. Setup a "live" project at Transifex.

  2. Ask your customer success manager (CSM) to enable translation for your docs project. If you have a group of projects, ask your CSM to enable translation for the group parent and any child projects you want to translate.

  3. Now that your CSM enabled translation, you have access to dash.readme.io/project/yourProject/translation on your dash. Configure it as follows:

Configuration optionDescriptionComment
LANGUAGE PICKERRecommended to enable this ReadMe language picker. If you enable this setting, be sure to disable Transifex's automatic language picker (see following steps).If it is enabled, the user sees a dropdown in the breadcrumb navigation to select their language, in addition to a language element in their URL path. For example, for a French translation, they'd see lang-fr in the URL, as in: `developer.myCompany.com/myProduct/lang-fr/docs/bienvenue.

For each docs project in your group, the language breadcrumb and URL element display or hide automatically, based on the languages you're managing for that project.

For more information on URL paths see URL paths in Readme.



If this is disabled, the user can instead pick from Transifex's language menu.
TRANSIFEX PUBLIC API KEYIn your Transifex live resource, click the Install Snippet button. From the code snippet window that launches, copy the API key and paste it here.
The code snippet is also available by clicking Resources, then select your website, then click Settings from the hamburger menu. The API key will probably look similar to this: 423e1bf0651d5046cf2cad6161c01051.
This API key is used for Transifex Live integration. For more information, see Installing the Transifex Live JavaScript Snippet.
TRANSIFEX SECRET API KEYIn Transifex, go to the main navigation, click your profile image, go to User Settings, and generate an API key. Probably looks similar to this: a/2f174555d2228cbab7b0c935aecb1bda9c3b4eac (including "/" as the second character).
TRANSIFEX ORGANIZATIONName of your Transifex organization.
TRANSIFEX PROJECTName of your Transifex project.

Translation configuration pane.

  1. Save your ReadMe project settings.

  2. Click Sync Languages, and save your settings again. This step re-indexes our search to contain localized documentation.

  3. If you have a group of docs projects, you need to copy the preceding configuration settings for each project. Copy the settings you used in the previous step, and paste them into your Group translation page at dash.readme.io/group/yourGroup/translation. Then copy them into any additional docs project in your group that you want to translate, at dash.readme.io/project/yourProject/translation. Save the configurations, then sync languages for each project.

  4. Add a '?transifex' parameter to the URL of the page you want to translate, and Transifex adds a sidebar to your documentation pages in which you can manage translation. For more information see Transifex documentation.

Transifex translation in progress.

  1. If you enabled the language picker at dash.readme.io/project/yourProject/translation (recommended), then disable Transifex's native language picker. In the Transifex pane, click the settings icon, then Language picker position > Do not place a picker.

Language picker hidden.

  1. When you're satisfied with your translations, click the Publish button on the Transifex sidebar. Then, users can pick which language to view.

language picker

Note that if you don't enable ReadMe's language picker and instead use Transifex's language picker, then you see Transifex's picker by default in the lower left of the screen:

Transifex language picker.

Updated 2 months ago


Language Support/Localization


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.