Missing type definitions for @docusaurus/theme-translations

[cmfcmf]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

I am trying to make my local search plugin (https://github.com/cmfcmf/docusaurus-search-local) work with Docusaurus beta 10+. #5849 has moved readDefaultCodeTranslationMessages to @docusaurus/theme-translations. However, the version of @docusaurus/theme-translations published to npm does not include type defintions for readDefaultCodeTranslationMessages. For more context on the migration see cmfcmf/docusaurus-search-local#82.

Steps to reproduce

• Install @docusaurus/theme-translations@2.0.0-beta.13
• Try to import readDefaultCodeTranslationMessages in a TypeScript project

• Could not find a declaration file for module '@docusaurus/theme-translations'. '/home/cmfcmf/dev/docusaurus-search-local/node_modules/@docusaurus/theme-translations/lib/index.js' implicitly has an 'any' type.

Expected behavior

@docusaurus/theme-translations should contain TypeScript definitions.

Actual behavior

@docusaurus/theme-translations does not contain TypeScript definitions.

Your environment

No response

Reproducible demo

No response

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Agree it's unexpected that it's not published https://unpkg.com/browse/@docusaurus/theme-translations@2.0.0-beta.13/lib/

This should fix it: #6088

However, I must warn that readDefaultCodeTranslationMessages is an internal API on which we can't guarantee retro-compatibility. If you use a test matrix strategy things might break depending on the version. But we probably won't refactor again in the near future.

You are implementing a single plugin, unlike us, so you can as well use a simpler approach and just have a translations.json file with locale keys?

This fn is mostly suited for our own use-case, as we need to split translations per plugin, but also gather them into a unique place so that files to translate are easier to find for our translators. You likely have different requirements, and our way of organizing translation is maybe not the best for a repo with a single plugin.

Maybe you could re-use codeTranslationLocalesToTry instead of readDefaultCodeTranslationMessages (both are internal methods) and build your own logic? Note that translations do not absolutely need to be JSON files, as long as the lifecycle returns them it will work

[cmfcmf]

Thank you for the additional insights! I think when I initially implemented i18n in my plugin I looked at how the core plugins were handling translations and copied that. I'll use codeTranslationLocalesToTry like you suggested and also make @docusaurus/theme-translations a direct dependency of my plugin pinned to an exact version for now. I think it would be sensible to make codeTranslationLocalesToTry or something similar part of the public API, since every plugin that includes translations would probably benefit from this logic.

[slorber]

Agree we could provide a convenient way for plugin authors to manage translations on disc, including the locale fallback strategy.

But it would probably be something different than readDefaultCodeTranslationMessages as this method seems better suited for internal usage (plugin authors probably want translations/<locale>.json instead of translations/<locale>/my-plugin.json

make @docusaurus/theme-translations a direct dependency of my plugin pinned to an exact version for now

This could be dangerous and fail, Docusaurus expects that all @docusaurus packages have the exact same version on startup