estruyf#89 - Documentation and enhancements

changelog.json

@@ -5,6 +5,12 @@
  { "id": null, "title": "" }
  ]
  },
+ {
+ "title": "1.11.0",
+ "updates": [
+ { "id": 89, "title": "[Enhancement]: Use Cognitive Service Translation API connection for machine translations" }
+ ]
+ },
  {
  "title": "1.10.0",
  "updates": [

cypress/integration/translator.ts

@@ -0,0 +1,25 @@
+/// <reference types="cypress" />
+/// <reference types="../support" />
+
+describe('Multilingual validation', function() {
+ const PAGE_URL = "sitepages/doctor/nl/page-creation.aspx";
+
+ /**
+ * Before visiting SharePoint, we first need to authenticate
+ */
+ before(() => {
+ cy.visitSP(PAGE_URL);
+ });
+
+ after(() => {
+ cy.screenshot();
+ });
+
+ it('1. Check if language selector is available on the page', () => {
+ cy.get(`[data-automation-id="LanguageSelector"]`).should('exist').should("contain.text", "Dutch");
+ });
+
+ it('2. Check if the page contains the right language contents', () => {
+ cy.get(`h2#page-creation`).should('exist');
+ });
+});

docs/content/docs/multilingual/index.md

@@ -30,7 +30,8 @@ Example setup:
  "languages": [
  1043
  ],
- "overwriteTranslationsOnChange": true
+ "overwriteTranslationsOnChange": true,
+ "translator:" null
  } 
 }
 ```
@@ -64,4 +65,36 @@ For the translation page, `home.nl.lang.md` in the above example, you should set
 
 By default, SharePoint will copy the header settings from the source page. If you want to override these settings, you can add the same options as all other pages as long as you make sure `type: translation` is set for these pages.
 
-> **Info**: Sample of how you can use multilingual with `doctor` has been provided in [https://github.com/estruyf/doctor-sample](https://github.com/estruyf/doctor-sample).
+> **Info**: Sample of how you can use multilingual with `doctor` has been provided in [https://github.com/estruyf/doctor-sample](https://github.com/estruyf/doctor-sample).
+
+## Using Azure Translator service
+
+If you want to make use of the Azure Translator service which is part of the [Azure Cognitive Services](https://azure.microsoft.com/en-us/services/cognitive-services/) family. You will first need to create the translator service in your Azure tenant and provide the following config:
+
+```json
+{
+ "multilingual": {
+ "enableTranslations": true,
+ "languages": [
+ 1043
+ ],
+ "overwriteTranslationsOnChange": true,
+ "translator:" {
+ "key": "<subscription key>",
+ "endpoint": "https://api.cognitive.microsofttranslator.com/",
+ "region": "<region name, example: westeurope>"
+ }
+ } 
+}
+```
+
+### Automatically translate pages
+
+When you want to make use of this APIs for page translations. All you need to do is specifying the `localization` property to its front matter of the page. In this case, you do not need to specify the path to the page. As the page will be translated on the fly.
+
+```yaml
+localization: 
+ "nl-nl":
+```
+
+> **Info**: When you are going to run `doctor`. There will be `*.machinetranslated.md` pages created next to the parent page. This is done to not create any conflicts with the referenced pages and images. At the end of the process, `doctor` will remove these generated pages. During a `debug` run, they will not be removed. 

docs/content/docs/options/_index.md

@@ -131,8 +131,24 @@ You can provide the same flags and values like in the parameters. Parameters can
  - **enableTranslations**: `boolean` - Specifies if you want to enable or disable multilingual features on the site. Default: `false`.
  - **languages**: `number[]` - Locale IDs (or LCIDs) to enable on the site. An overview of the supported LCIDs for SharePoint can be found on [Supported LCIDs by SharePoint](https://github.com/pnp/PnP-PowerShell/wiki/Supported-LCIDs-by-SharePoint).
  - **overwriteTranslationsOnChange**: `boolean` - Specify whether the changes made to user-specified text in the default language should automatically overwrite the existing translations made in all alternate languages.
+ - **translator**: `Translator` - This property allows you to specify the Azure Translator Cognitive Service. When Specified, you allow `doctor` to use the translator APIs to machine translate your pages.
 
-Example:
+Manual translation example:
+
+```json
+{
+ "multilingual": {
+ "enableTranslations": true,
+ "languages": [
+ 1043
+ ],
+ "overwriteTranslationsOnChange": true,
+ "translator:" null
+ } 
+}
+```
+
+Machine translation example:
 
 ```json
 {
@@ -141,7 +157,12 @@ Example:
  "languages": [
  1043
  ],
- "overwriteTranslationsOnChange": true
+ "overwriteTranslationsOnChange": true,
+ "translator:" {
+ "key": "<subscription key>",
+ "endpoint": "https://api.cognitive.microsofttranslator.com/",
+ "region": "<region name, example: westeurope>"
+ }
  } 
 }
 ```

src/helpers/MultilingualHelper.ts

@@ -150,7 +150,7 @@ export class MultilingualHelper {
  } else {
  if (options.multilingual && options.multilingual.translator) {
  const { translator: { key, endpoint, region } } = options.multilingual;
- if (key && endpoint) {
+ if (key && endpoint && region) {
  const contents = fs.readFileSync(filePath, { encoding: "utf-8" });
  const markup: matter.GrayMatterFile<string> = matter(contents);
  const { content, data } = markup;
@@ -175,6 +175,14 @@ export class MultilingualHelper {
  const pageTranslation = transContent[0].translations;
  Logger.debug(`Create new page for translations`);
 
+ if (data.menu) {
+ for (const location in data.menu) {
+ if (location) {
+ data.menu[location].id = data.title.toLowerCase().replace(/ /g, "-");
+ }
+ }
+ }
+
  const pagePath = TempDataHelper.createPage(path.dirname(filePath), path.parse(filePath).name, matter.stringify(pageTranslation.map(t => t.text).join(' '), data));
 
  const translatedPage = await this.getTranslatedPage(locale, translatedPages, url, slug, token);

src/models/Menu.ts

@@ -4,15 +4,16 @@ export interface Menu {
  [name: string]: MenuType;
 }
 
-export interface MenuType {
- /**
- * Type of menu where the items will be added. Default is "QuickLaunch".
- */
+
+/**
+ * Type of menu where the items will be added. Default is "QuickLaunch".
+ */
+ export interface MenuType {
  items: MenuItem[];
 }
 
 export interface MenuItem {
- url: string;
+ url?: string;
  id: string;
 
  name?: string;