Dynamics 365 Business Central: helpBaseUrl and supportedLocales for Localization apps (Help Links)

Hi, Readers.
Today I would like to share a point in the development of localization language packages, helpBaseUrl and supportedLocales.

Contents

What is helpBaseUrl?
How to create helpBaseUrl?

What is helpBaseUrl?

Specifically for localization apps that translate Business Central into languages that are not offered by Microsoft, the app.json file must be set to specify the destination of links to Help as shown in the following example:

  "helpBaseUrl": "https://mysite.com/{0}/documentation/",
  "supportedLocales": [
    "ja-JP", "zh-CN"
  ],

The helpBaseUrl and supportedLocales properties specify that the links to the Help must go to the mysite.com site when the user is using the product in Japan and China. If the user switches the application language to English (US), then the Help calls will go to the docs.microsoft.com site.

JSON Files

Setting	Mandatory	Value
helpBaseUrl	No	The URL for the website that overtakes all Help for the specified locales. This property is intended for localization apps specifically since the setting overwrites the default URL of `/{0}/dynamics365/business-central`. If you set this value, you must also specify one or more languages in the `supportedLocales` setting.
supportedLocales	No	The list of locales that are supported in your Help if different from all locales. The value on the list is inserted into the URL defined in the `contextSensitiveHelpUrl` and `helpBaseUrl` properties. The first locale on the list is default. An example is `"supportedLocales": ["da-DK", "en-US"]` for an app that supports only Danish and English (US).

PS:
1. How to open help link in Business Central.
Use shortcut key Ctrl + F1, or choose Help & Support.

Then click then link after Learn more about your current task or page.

The Help link will be opened.

2. error PTE0009: The app.json ‘helpBaseUrl’ property must not be used for per-tenant extensions.

How to create helpBaseUrl?

Pre-requisites: Git and Visual Studio Code (Recommend)

There are several ways to create helpBaseUrl. In this post, I mainly introduce using docFX to do it which is an open-source tool for converting markdown files.

Install docFX

1. Download docFX.
https://github.com/dotnet/docfx/releases

2. Extract the file

3. System -> Advanced system settings

4. Environment Variables…

5. Select Path in System variables, and then choose edit.

6. Choose New.

7. Enter the path to the docFX folder you just Extracted.

Choose OK.

8. Run Windows PowerShell ISE to test.

Run command: docfx init -q

If no error is reported, docFX installation is successful.

Download Microsoft Docs and Create helpBaseUrl

1. If you want to download, customize or extend the Microsoft Help, you can fork the source repo in English (US).
https://github.com/microsoftdocs/dynamics365smb-docs

Welcome to the repository for the application help content for Dynamics 365 Business Central! This repo gives you access to the source files for the enduser Learn More content. It also provides a way for you to actively contribute to the current Business Central content.

2. Clone the source code.
git clone https://github.com/microsoftdocs/dynamics365smb-docs

Clone Completed.

3. Open the downloaded folder with Visual Studio Code.

4. You can find docfx.json file in “~dynamics365smb-docs\business-central”

Run command:
docfx “C:\Temp\dynamics365smb-docs\business-central\docfx.json”

File generating..

Completed. There may be warning messages, You can ignore them.

PS: If no warnings and errors.

5. A new folder named d365businesscentral has been automatically generated.

The helpBaseURL has been generated.

For Example:

Video:

Now if possible, all documents can be translated into the your local language.

In fact, up to this point, helpBaseUrl for Business Central has been created. But I am sure many of you have noticed that the content has been downloaded, but the template of the website is in docFX standard. So how to modify the template.

Modify website template

1. Export docFx template.
Run command: docfx template export default

Completed.

The template files will be exported to the “~dynamics365smb-docs_exported_templates\default”.

2. Modify website template
For example:
footer

background color of navbar

favicon and logo

……

3. After all the modifications are completed, return to the docfx.json file in “~dynamics365smb-docs\business-central”. And then specify the path of the template folder.

4. Run the docfx command again:
docfx “C:\Temp\dynamics365smb-docs\business-central\docfx.json”

Completed.

It looks good.

Deploy content to your website

You can deploy your website on your local PC, but there are two things to note.
1. Must contain the folder set in supportedLocales, such as zh-CN.

2. As with language to English (US), the help site opens without “.html” suffix, so you need to add rules in IIS.

Add new website in IIS.

Create a new “.htaccess” file in the root directory. And then add the following rules.
RewriteRule ^bai(.)/([\w-]+)\?(.)$ $1/$2.html\?$3
RewriteRule ^(.*)/([\w-]+)$ $1/$2.html

Choose URL Rewrite.

Import Rules

Import “.htaccess” file.

Then choose Apply.

Now, you can access the sites.
http://localhost:8081/zh-CN/d365businesscentral/sales-how-sell-products

Finally, go back to the app.json file, add the following setup. Then publish.

  "helpBaseUrl": "http://localhost:8081/{0}/d365businesscentral/",
  "supportedLocales": [
    "ja-JP", "zh-CN"
  ],

Test Video: en-US -> zh-CH

END

Hope this will help.

Thanks for reading.

ZHU