Transifex

Transifex is a SAAS application that allows web platforms/sites to include a JS snippet (managed by Transifex) which translates your content upon load.

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.

Here is a simple diagram of how a ReadMe documentation portal would work with Transifex:

Transifex works with ReadMe by allowing users to add a custom javascript snippet in a documentation portal. Once loaded, the Transifex vendor logic will retrieve the necessary data to render the content into another language. To see how Transifex works in detail, please refer to their learning center.

Sample Localized Docs

For examples of ReadMe docs localized with Transifex, see:

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 Product Experience Manager (PXM) to enable translation for your docs project. If you have a group of projects, ask your PXM to enable translation for the group parent and any child projects you want to translate.

  3. Now that your PXM 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 ORGANIZATION URLName of your Transifex organization. This should be the organization URL.Next to your profile icon, select your organization dropdown > select 'Organization Settings'. Copy your Organization URL (after www.transifex.com/)
TRANSIFEX PROJECT URLName of your Transifex project.Dashboard > Your Project > Settings > General > Your project URL

Organization URL

944

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.

727

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.
547

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.
579

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:

625

Transifex language picker.