From bcba05ae03e3ce349510ddac6551eac21e2ea809 Mon Sep 17 00:00:00 2001 From: Eric Nakagawa Date: Wed, 18 Oct 2017 12:55:58 -0700 Subject: [PATCH] Adds sitemap.xml. Adds 'Help Translate' to translatable strings. Error messages and fn name cleanups. (#136) * added a note about needing more than one language to be enabled to allow for a drop down * Removing debug statements * Add 'Help Translate' to translatable strings, improves error messages around missing translated strings, calls write-translations on some routes * Adds sitemap.xml to live server and build. Versioning not supported. -- Also did some file name and module cache cleanups. --- docs/api-site-config.md | 4 +- docs/guides-translation.md | 49 ++++++++++++++++--- lib/core/Doc.js | 48 +++++++++--------- lib/core/Site.js | 59 +++++++++++++---------- lib/core/nav/HeaderNav.js | 47 +++++++++--------- lib/server/feed.js | 4 +- lib/server/generate.js | 99 +++++++++++++++++++++----------------- lib/server/readMetadata.js | 97 ++++++++++++++++++++----------------- lib/server/server.js | 67 ++++++++++++++++++-------- lib/server/sitemap.js | 94 ++++++++++++++++++++++++++++++++++++ lib/server/translate.js | 7 ++- lib/server/translation.js | 2 + lib/write-translations.js | 39 +++------------ package.json | 3 +- website/i18n/en.json | 6 ++- website/package.json | 10 +++- website/pages/en/index.js | 20 +++----- website/siteConfig.js | 2 +- yarn.lock | 83 ++++++++++++++++++++++++++++++++ 19 files changed, 495 insertions(+), 245 deletions(-) create mode 100644 lib/server/sitemap.js diff --git a/docs/api-site-config.md b/docs/api-site-config.md index e19e5f3517..deac13c5d3 100644 --- a/docs/api-site-config.md +++ b/docs/api-site-config.md @@ -75,7 +75,7 @@ headerLinks: [ `footerIcon` - url for a footer icon. Currently used in the `core/Footer.js` file provided as an example, but it can be removed from that file. -`recruitingLink` - url for the `Help Translate` tab of language selection when languages besides English are enabled. This can be included you are using translations but does not have to be. +`translationRecruitingLink` - url for the `Help Translate` tab of language selection when languages besides English are enabled. This can be included you are using translations but does not have to be. `algolia` - Information for Algolia search integration. If this field is excluded, the search bar will not appear in the header. @@ -130,7 +130,7 @@ const siteConfig = { disableTitleTagline: true, separateCss: ["static/css/non-docusaurus", "static/assets/separate-css"], footerIcon: "img/docusaurus.svg", - recruitingLink: + translationRecruitingLink: "https://crowdin.com/project/docusaurus", algolia: { apiKey: diff --git a/docs/guides-translation.md b/docs/guides-translation.md index b14830abd6..0c891b88f0 100644 --- a/docs/guides-translation.md +++ b/docs/guides-translation.md @@ -29,7 +29,7 @@ crowdin.yaml The `pages/en/help-with-translations.js` file includes the same starter help page generated by the `examples` script, but now includes translation tags. -The `languages.js` file tells Docusaurus what languages you want to enable for your site. +The `languages.js` file tells Docusaurus what languages you want to enable for your site. By default, we expect English to be enabled. The `crowdin.yaml` file is used to configure crowdin integration, and is copied up one level into your docusaurus project repo. If your docusaurus project resides in `/project/website`, then `crowdin.yaml` will be copied to `/project/crowdin.yaml`. @@ -95,9 +95,9 @@ This section provides context about how translations in Docusaurus works. ### Strings -A Docusaurus site has many strings used throughout it that require localization. However, maintaining a list of strings used through out a site can be laborious. Docusaurus simplies this by centralizing strings. +A Docusaurus site has many strings used throughout it that require localization. However, maintaining a list of strings used through out a site can be laborious. Docusaurus simplifies this by centralizing strings. -The header navigation, for example can have links to 'Home' or your 'Blog'. This and other strings found in the headers and sidebars of pages are extracted and placed into `i18n/en.json`. When your files are translated, say into Spanish, a `i18n/fr.json` file will be downloaded from Crowdin. Then, when the Spanish pages are generated, Docusaurus will replace the English version of corresponding strings with translated strings from the corresponding localized strings file (e.g. In a Spanish enabled site 'Help' will become 'Ayuda'). +The header navigation, for example can have links to 'Home' or your 'Blog'. This and other strings found in the headers and sidebars of pages are extracted and placed into `i18n/en.json`. When your files are translated, say into Spanish, a `i18n/es-ES.json` file will be downloaded from Crowdin. Then, when the Spanish pages are generated, Docusaurus will replace the English version of corresponding strings with translated strings from the corresponding localized strings file (e.g. In a Spanish enabled site 'Help' will become 'Ayuda'). ### Markdown Files @@ -105,12 +105,45 @@ For documentation files themselves, translated versions of these files are downl ### Other Pages -For other pages, Docusaurus will automatically transform all `` tags it finds into function calls that return the translated strings from corresponding localized _`locale`_`.json`. +For other pages, Docusaurus will automatically transform all `` tags it finds into function calls that return the translated strings from the corresponding localized file _`locale.json`_. ## Crowdin +Crowdin is a company that provides translation services. For Open Source projects, Crowdin provides free string translations + Create your translation project on [Crowdin](https://www.crowdin.com/). You can use [Crowdin's guides](https://support.crowdin.com/translation-process-overview/) to learn more about the translations work flow. +Your project will need a `crowdin.yaml` file generated. + +The example below can be automatically generated by the docusaurus cli with the `examples` script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded. + +Below is an example crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Behasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional. + +```yaml +project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID +api_key_env: CROWDIN_DOCUSAURUS_API_KEY +base_path: "./" +preserve_hierarchy: true + +files: + - + source: '/docs/*.md' + translation: '/website/translated_docs/%locale%/%original_file_name%' + languages_mapping: &anchor + locale: + 'de': 'de' + 'es-ES': 'es-ES' + 'fr': 'fr' + 'ja': 'ja' + 'ko': 'ko' + 'mr': 'mr-IN' + 'pt-BR': 'pt-BR' + 'zh-CN': 'zh-Hans' + 'zh-TW': 'zh-Hant' +``` + +You can [go here]() to learn more about customizing your `crowdin.yaml` file. + ### Manual File Sync You can add the following to your `package.json` to manually trigger crowdin. @@ -124,11 +157,13 @@ You can add the following to your `package.json` to manually trigger crowdin. These commands require having an environment variable set with your crowdin project id and api key (`CROWDIN_PROJECT_ID`, `CROWDIN_API_KEY`). You can add them inline like above or add them permanently to your `.bashrc` or `.bash_profile`. -If you run more than one localized Docusaurus project on your computer, you should change the name of the enviroment variables to something unique (`CROWDIN_DOCUSAURUS_PROJECT_ID`, `CROWDIN_DOCUSAURUS_API_KEY`). +If you run more than one localized Docusaurus project on your computer, you should change the name of the enviroment variables to something unique (`CROWDIN_PROJECTNAME_PROJECT_ID`, `CROWDIN_PROJECTNAME_API_KEY`). -### Automated File Sync +### Automated File Sync Using CircleCI -To automatically get the translations for your files, update the `circle.yml` file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example `circle.yml` file: +You can automate pulling down and uploading translations for your files using the [CircleCI](https://circleci.com) web continuous integration service. + +First, update the `circle.yml` file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example `circle.yml` file: ```yaml machine: diff --git a/lib/core/Doc.js b/lib/core/Doc.js index 070202fce0..56f67249a7 100644 --- a/lib/core/Doc.js +++ b/lib/core/Doc.js @@ -11,40 +11,38 @@ const Marked = require("./Marked.js"); // inner doc component for article itself class Doc extends React.Component { render() { - let editLink = - !this.props.version && - this.props.config.editUrl && - - Edit this Doc - ; - if (this.props.language != "en") { - editLink = - !this.props.version && - this.props.config.recruitingLink && + let editLink = !this.props.version && + this.props.config.editUrl && ( - Translate this Doc - ; + href={this.props.config.editUrl + this.props.source} + target="_blank"> + Edit this Doc + + ); + if (this.props.language != "en") { + editLink = !this.props.version && + this.props.config.translationRecruitingLink && ( + + Translate this Doc + + ); } return (
{editLink} -

- {this.props.title} -

+

{this.props.title}

- - {this.props.content} - + {this.props.content}
); diff --git a/lib/core/Site.js b/lib/core/Site.js index d114c688ef..88d77919f7 100644 --- a/lib/core/Site.js +++ b/lib/core/Site.js @@ -31,6 +31,7 @@ class Site extends React.Component { this.props.config.baseUrl + (this.props.url || "index.html"); let latestVersion; + if (fs.existsSync(CWD + "/versions.json")) { latestVersion = require(CWD + "/versions.json")[0]; } @@ -54,12 +55,13 @@ class Site extends React.Component { {this.props.children}