Migrate PHP website to MkDocs

Feedback News
1

I’m migrating the legacy PHP website to a static site generator to simplify deployment and streamline content management.

Rationale

We currently require an Apache web server because we depend on .htaccess for pretty URLs. The web server also requires PHP, gettext, and locales. I also use PEAR::HTTP2 for language negotiation. A few days ago I tried to upgrade the software stack and things started breaking left and right. For example, PEAR::HTTP2 hasn’t been updated since 2016 and is therefore no longer compatible with current PHP versions.

Then I started looking into search functionality. I found some popular solutions meant for static sites. These are out of the questions as long as we depend on PHP. Other solutions would require me to install additional tools on the web server, which is often not possible with third-party hosting services. Docker would have been a possibility, but our current host doesn’t support that either.

Long story short, migrating to a static site generator would solve all of the above issues.

Path forward

I have selected Material for MkDocs. This stack provides the desired “Material Design” aesthetic and functionality (Admonitions, Search, Top Navigation) out-of-the-box, while allowing us to inject our custom footer via template overrides.

We will transition from PHP + gettext to Markdown Parallel Content Files, utilizing Weblate’s Translation Memory to migrate existing translations automatically.

Action plan

I’m tracking progress on GitLab:

Weblate translations

I’m still figuring out how to integrate this new setup with Weblate. My intention is to make the transition as seamless as possible. A significant amount of effort has gone into the translations and I don’t want any of the work done so far to be lost in the process.

  1. I created a Legacy translations glossary, containing all translations from the legacy PHP site.
  2. I’ve enabled Translation Memory so that translations are shared between components.
  3. I will add new translation components for the new Markdown content.
  4. New components will automatically receive translations through Translation Memory.
  5. Add-ons enabled project wide:
    1. Add missing languages: Ensures a consistent set of languages is used for all components within a project.
    2. Automatic translation:
      • Automatic translation mode: Add as translation
      • Query: state:<translated
      • Source of automated translations: Machine translation
      • Machine translation engines: Weblate Translation Memory
      • Score threshold: 100
    3. Automatic translation:
      • Automatic translation mode: Add as suggestion
      • Query: state:<translated
      • Source of automated translations: Machine translation
      • Machine translation engines: Weblate Translation Memory
      • Score threshold: 80

Tips for translators

  1. If the current string has a match with the Translation Memory, it should appear under the “Automatic suggestions” tab. Look for suggestions coming from the legacy getgnulinux-pot component (see the “Origin” column). It’s best to ignore translations from “LibreTranslate” because they are of poor quality.
  2. I have found that despite the Translation Memory, many strings are not matched because the Markdown syntax is too different. For this reason I created a Legacy translations glossary, containing all translations from the legacy PHP site. If no match is found in the Translation Memory you will still be able to find all the original translations in this glossary. Be sure to replace the HTML tags by the corresponding Markdown syntax when copying translations from the glossary.
2

I have completed the migration to Material for MkDocs. It was a bit tricky to get this new setup integrated with Weblate, but in the end it worked out pretty well. But there are some regressions:

  • Weblate replaces URLs by placeholders in translatable strings, so URLs are no longer translatable. I find this acceptable. In fact, I think it improves the translation experience.
  • The Asturian language is not supported at the moment, see https://github.com/ultrabug/mkdocs-static-i18n/issues/339. I’m afraid there is no simple fix at the moment, but I will continue to look for a solution. For the time being, I will remove Asturian from the project, so that people don’t waste time translating to a language that we can’t support at the moment.
  • One of the reasons I chose Material for MkDocs is for it’s built-in search functionality. Unfortunately, enabling the Tamil language breaks the search functionality completely due to a bug in Lunr.js. I haven’t found a solution for this yet, but for now I will have to disable the search functionality as long as Tamil is enabled.

All in all, I’m satisfied with the new setup. It makes my life easier, in terms of maintaining the website. And hopefully this is also a step up for the translators, since it’s now possible to translate one page at a time. This also allows me to set a translation priority for each page. If you have any feedback regarding the new setup, please let me know.