I18n, l10n, at least translation discussion

Development Documentation
1

Hi, community!

I noticed there is none of the ongoing discussion about translations.
And it would be great if NixOS provide translated manuals for several languages at the start.
It can bring much more interest into the community.

Of course, there’s some possibility that I couldn’t find a good pointer to the discussion about translation projects, but if there’s none, what’s the community’s view on this subject?

If a new project starts, I can contribute a Korean translation, and also as I’ve experienced, CJK(Chinese, Japanese and Korean) translators are everywhere however the project is a niche one.

Sorry, if it was already discussed or it isn’t the priority for Nix community.

Thanks :slight_smile:

// English is not my mother tongue so if there’s a mistake in grammar or typo, please let me know, and I’ll explain it more precisely or fix it!

9 Likes
2

Just so we’re on the same page, so we’re talking about the same thing, you’re talking about Nix, Nixpkgs, and NixOS-specific manuals and software, right? The NixOS Linux distribution should handle i18n/l10n correctly for software that that has correct i18n/l10n already.

The problem is, as I understand, two-fold.

AFAIK the main issue is lack of initial people-power (free developer time) to put in the development required to add multiple languages support in the software and development stack. Though this is a mostly one-time investment in time. Further maintaining the implementation of i18n/l10n is close to a rounding error once it’s done (does not require a lot of developer time to maintain).

But wait, there’s more. What’s actually “expensive” in developer time is properly maintaining the translations, and making sure changes to “native” (e.g. english here) texts are reflected in the translations. The technical aspect of this is probably not much of an issue. It’s a problem solved multiple times in different projects. The main issue, I suppose, will be about the content of the translations.

Anyway, the reason I’m saying all that is that it’s likely it’s a desired feature, but no one has had the time and enough interest to invest in making what’s missing for this.

I will add that I strongly believe this is a crucial lacking feature in the Nix ecosystem. This will slow down adoption from people that don’t know english well enough. Furthermore, some jurisdictions in the world require that software be available in a specific language. For some jurisdictions it will only apply for state-level work, but for some other it may involve any work.

I don’t know how much effort I can put in helping with this, but I will help i18n/l10n efforts as much as I can.

3 Likes
3

OK, I brought a ‘Super Minimal Viable Project’ - NixCT here.

‘NixCT’ is just a placeholder (but has the meaning of ‘Nix Contributors’ Translations’)

Only the index page and preface of nixpkgs manual are built.
Also, only Korean translations of them is shown.

Currently

  • Built with readthedocs.org
  • Made a template repository in github
    • This repository will be used as en_US documents
  • Translators can take the template repository and name their new repository as NixCT-ko_KR (${language-code}_${country_code})
  • Then, the admin can import the repository and add it as translated version in the main readthedocs project dashboard.
  • Document sync can be achieved via a tag. For example, if the template version provides 21.09-doc3 version, other translation projects can sync via tags.
  • Only problem is synchronizing the template version with the official manual. There should be a slight rename/remove/restructure process, so it would be really hard to maintain synchronization.

maybe Future

  • community can link this page with a subdomain of nixos.org, such as docs.nixos.org
  • community can take the whole template repository and manage it better than me.
  • community can restructure the original document directory, with this translation project in mind.

Is this project ‘No Go’? What’s your opinion?

(BTW, there’s also weblate solution)

EDIT[0]: typo

4

As you already mentioned Weblate, I wanted to add, that I’m currently working on a NixOS module to deploy Weblate.

It is already in a testable state and is to be merged into Nixpkgs eventually.

1 Like
5

Great News!! How did I miss the news :slight_smile:

And I’ll remove all my projects!

6

Just saying, the docs aren’t being built (AFAICT), and the repo is not public at this time.

¯\_(ツ)_/¯

I think if no one moves, nothing will happen. In that sense it’s better than no go, as a community project. As far as the technical side goes, I have no actual experience in OSS projects translation. So I can’t say if on the technical side of things this is right or not.

My main worries are “keeping up” with the usptream docs.

By the way, I do have relevant technical translation experience. Part of a previous job of mine included doing, maintaining, and decision making about translations between French/English, but no experience on deciding much on the “tooling” side. And no tooling experience for long form text; it was all application strings translation.

I will try and take time to do 1:1 translation English → French*, following your methods, so I’ll be able to tell my opinion after this is started I guess.

*: (fr_CA/Québec, which mean Québécois neologisms rather than French neologisms)

7

Ah! This explains why your project is gone!

How’s weblate for “long form” documentation? From their website it looks much more focused towards application strings. Or is long form documentation needing another tool still?

8

This is a great goal, but I don’t think there are nearly enough volunteers to maintain all the translations. For example, just the transition from docbook to markdown of the Nixpkgs and NixOS manuals has been going on for over a year and it’s not done yet.

1 Like
9

(My emphasis)

It’s possible, and that’s one of the main concerns to have with translations. The tooling should allow properly conveying to end-users that the translations are not up-to-date in that case.

(My emphasis)

I think this point of view is unfair. It is a different kind of work, and requires a different skill set.

Additionally, I don’t know that the issues in the migration from docbook to markdown is strictly a people-hour issue. I believe there are other foundational issues causing some paralysis in moving forward, in addition to technological decisions not made yet.

These issues and the authoring format of the manuals does not matter as much as the contents does with translation. Sure, whenever the authoring format migration finishes, the authoring effort will need to apply the format changes. But the hard part with translating is not the authoring format, it’s translating. I would even assume that migrating to the new authoring format should be relatively straightforward with verification by native speakers, even without being experienced in translating the content.

I say we should start looking at the tooling right now, this is the exact right moment, when the tooling for the documentation authoring needs to be reviewed anyway. If deficiencies are found with the new authoring tooling with regards to translation, it will be easier to figure out early on rather than when it’s all done and finished.

Furthermore, there’s already one project in the Nix ecosystem where the documentation authoring is migrated in its final form: Nix itself! I think it’s at the right point, maybe even past the right point, to look into.

If I knew what technical tools to use for this, I would actually start looking into it right now with the Nix documentation. Setting up the framework, and using it by providing translations.

If we stamp down efforts because of only tangentially unfinished work and issues elsewhere, at best we’re only delaying efforts, but really I fear it’s extinguishing efforts for much later.

2 Likes
10

I believe there are other foundational issues causing some paralysis in moving forward, in addition to technological decisions not made yet.

True, changing the format was a complication and required more time (like figuring out to reproduce some docbook feature in markdown), but a large part of the work was rewriting all the chapters and reviewing the pull requests. The latter was done by just a handful of (amazing) people from what I recall.

If we stamp down efforts because of only tangentially unfinished work and issues elsewhere, at best we’re only delaying efforts, but really I fear it’s extinguishing efforts for much later.

Yes, I didn’t mean to dissuade anyone from attempting this: I just think that it will probably require new maintainers joining the effort, possibly setting up a platform to allow contributing without writing code or using git.

2 Likes
11

Thank you for putting it in words :).

Yes. I believe so too. This is why I believe the first step, and I’m getting myself involved into this, is to figure out what tooling and methods works already.

1 Like
12

I appreciate this effort, I agree that this is important.

I guess I’ll report on my very limited experience:
I had a pleasant time contributing to the localization of the Rust website using their Pontoon instance (until I realized that I sucked at doing it), you can read about their guidelines here. Pontoon is developed and used by Mozilla, it supports a wide range of formats (Fluent seemed technically appealing) and integrates with Git. It seems like you can even meta-search across multiple projects, in order to help with consistent translations.
In what I’ve seen so far, content is broken up, as it was for “application-style” localization, with the bigger chunks being one whole paragraph.

2 Likes
13

Thanks, will look into that. The fact it’s “application-style” with paragraphs split into discrete strings tells me it’s possible that whole documents translations aren’t a solved problem.

Which means you’re better than some who continue even though they suck at doing it :slight_smile: You did a good job understanding and knowing your limits.

EDIT: Looks like the pontoon is strictly for the website contents.

The different docs are being translated in ad-hoc ways it looks like? I’m currently looking into it.

The methodology seems to be “copy the repo; translate contents”… Which makes me wonder how it works through content updates. Unless the book isn’t updated?

  • https://github.com/Jimskapt/rust-book-fr/pull/274

Indeed it seem to be. Take the diff from last time it was synced, then edit appropriately.

Further EDIT: Seems similar at PHP

  • https://github.com/php/doc-fr/pull/121

Another EDIT: Guix docs and websites go through weblate, through different schemes it seems…

(docs)

(website)

Sphinx seems to have a .po based workflow for long-form documentation.

Fedora also uses a docbook-driven documentation translation system.

But this doc might be outdated. I can’t exactly confirm.

Similarly for Ubuntu

A .po translation approach to long form docs.

Similarly for python (unsurprisingly) using .po, I presume generated by the previously described Sphinx workflow.

3 Likes
14

I spent some time looking at all those, thinking, thinking a bit more.

I have an idea for two different, but mostly-similar in caveats workflows for long form documentation.

But, I’m not stating them publicly just yet. Why? I want to hear other voices first, if anyone has any proposition for workflows, either concrete or vague, please share!

Reminder of the scope: Translate the Nix documentation (only).

Do not go and translate it just yet. Only consider the current format and propose methods of handling (multiple) translations. This includes figuring out how to maintain translations as the contents evolve.

1 Like
15

OK,

  • First of all, I’m not a dev guy, but just a doc guy. So, I know nothing about infrastructure, and no matter which software is used, if there’s any opened door, I deep dive and translate.
  • Second, Korean users need documentation. Also, I personally really love this Nix idea. So I want to spread this idea as soon as possible.
  • Third, my man-power is not that expensive. That means, if you guys reach an agreement about which software is perfect for this workflow, I can migrate the whole translated document without any extra burden. No worries. My work is really cheap compared to the dev team.

With those in mind, I started translating the documents, anyway.

Nix manual is done Ch1 through Ch4.
And I already have my own blog for Korean linux lovers who can’t fluently read or write in English.
So, I uploaded it there.

By the way, the translated documents will also be uploaded in forked ‘nixos/nix’ repository,
under the name of ‘nix/doc/manual/src-ko_kr’.
If I’m done with the translations, I’m thinking about a pull request.

6 Likes