Internationalization support

[ysh83737]

Search terms

• internationalization
• multi-language
• languages
• zh-cn
• en-us

Question

The project currently only provides English. Are there any plans to provide other languages? Maybe we can use i18n to achieve that.

[Gerrit0]

No plans to do this today, #2332 is what I'd recommend at this point

[ysh83737]

No plans to do this today, #2332 is what I'd recommend at this point

Thanks for reply, I'll think of some implementation options. Until then, I will post it in this issue.

[ysh83737]

@Gerrit0 Hi, Gerrit. I am trying to use i18n to achieve it. Please see if this is a feasible solution.
Here is my development branch. And here is a demo for it.
Thank you.

[Gerrit0]

Ah, you meant for pieces of the site itself! I thought you were referring to including multiple languages in comments for the source code.

I'm certainly open to including options for localization in TypeDoc, but have concerns with the implementation method you went with:

1. I'm very wary of adding dependencies. i18next is definitely less of a problem than i18n, which I thought this used at first, but it still seems strange for something that's essentially just a map... am I missing some reason to use a dependency here?
2. Recursing into plugin folder structures is extremely brittle and forces a structure which I don't want to do. It also prevents plugins from using declaration merging to ensure that they add the same keys for translation as is used when rendering.
3. To properly support locales, it needs to be available during conversion, not just during rendering. This is because presumably someone doing this would also want to override things like the group names "Enumeration Members", which happen during conversion.
4. Locales are configured (almost) completely separately from the rest of the options, I'd rather this live within TypeDoc's normal options structure. If someone wants to separate it out, config files can be regular JS, so they can import the configuration they want and merge it into the object given to TypeDoc.

With all this in mind, the design I'm thinking of is:

// interface with all translatable strings so that:
// 1. TypeDoc's schema generator for JSON options can provide reasonably good autocomplete for builtin strings.
// 2. Translation `t` calls can be properly type checked.
// 3. Plugins which add additional translated strings can use declaration merging to add new keys to this interface.
interface TranslatableStrings {
    settings: string;
    content: string;
}

// New member added to the Application class
// Defined here for easy access on plugins, and because it will be used in multiple phases of TypeDoc's run
class Application {
    i18n: I18N;
}

class I18N {
    setActiveLanguage(lang: string): void; // Called by Application.bootstrap after options have been read.
    translate(key: keyof TranslatableStrings): string;
    // may be called by plugins
    // will be called by Application.bootstrap to merge in any translations added by user configuration
    addTranslations(lang: string, translations: Partial<TranslatableStrings>, override = false): void;

   private translations: Record<string, Record<string, string>>;
}

// t method should be on context, not PageEvent
class DefaultThemeRenderContext {
  t(key: keyof TranslatableStrings): string;
}

// Users should be able to specify translations with:
// typedoc.json:
{
  "locales": {
    "default" { // or a language identifier like zh
      "settings": "Settings"
    }
  }
}

// If someone wanted to use json files
// typedoc.js
export default {
  locales: {
    zh: JSON.parse(readFileSync("./locales/zh.json"))
  }
}

I'd like to unify the htmlLang and lang options -- probably just a rename of htmlLang is appropriate. I think this feature deserves a non-patch release, so breaking changes are acceptable.

[ysh83737]

You do think better! Do you have a schedule for this feature? What can I do to help?

[ysh83737]

If you consider a website like crowdin to provide translating contribution. You can create a blank translation project first. And then I can start picking out some pieces that need to be translated.

[Gerrit0]

I try not to give dates for features, as that tends to be a recipe for disappointment as I don't always have time to work on typedoc, or get excited about other projects and abandon it for a few weeks.

That said, this is a fairly straightforward update... going to spend an hour or two looking at it today, so who knows.

Could you help me understand why I should use something like crowdin rather than just a folder of localizations in this repo? I'm having difficulty getting past their marketing to the why

[Gerrit0]

fairly straightforward

These words don't taste too good 6 hours in.

There's an i18n branch on the this repo with my current progress.

• Build an Internationalization class as described above (some changes due to requirements I forgot about)
• Review/update 113 log messages to use i18n
• Figure out how to handle translating option descriptions (This one is really annoying, options are a totally separate system which doesn't know about Application, intentionally, so that that system is easier to understand... Maybe option declarations can reference a translation key instead of having the description embedded? Hmmm...)
• Update ReflectionKind stringification to support i18n
• Update group plugin to use i18n reflection kind strings
• Update theme to use internationalized strings
• Consider moving localization strings to @typedoc/locale-X packages - it'd be nice to be able to update a locale without having to make a full release of TypeDoc. This probably requires figuring out how to do a monorepo for real, and will also require getting in touch with whoever it was that parked the @typedoc namespace on npm, since I don't own it.

[Gerrit0]

Initial pass through all of TypeDoc with adding support for localized strings is done! the i18n branch has the current state of everything. There are ~250 strings that can be customized, visible in translatable.ts.

It's also worth pointing at internationalization.ts which discusses which strings I considered translatable, vs which were left directly as English in the source. The internal-docs/internationalization.md page discusses adding translations to TypeDoc.

Remaining work:

• Review 91 throw occurrences for localizable strings (edit: +20 strings)
• Consider @typedoc/locale-x
• Add locales option to let users overwrite a few translations directly without having to define a plugin or get it added to TypeDoc.
• Figure out how translations can be reviewed - I certainly don't have the expertise to do so... maybe follow in Definitely Typed's footsteps and ask translation submitters to find someone who can review their work + include names at the top of the locale file for future translation contributors? (Maybe this is what crowdin makes easier?)

[Gerrit0]

@shlomiassaf it looks like you own the @typedoc organization on npm, according to some really old discussion in #595. Could you transfer that ownership to me so that it can be used for this?

[Gerrit0]

Fixed with TypeDoc 0.26, which is releasing 2024/06/21