Translation of Hugo-docs

dev
1

My Intention is to internationalize the documentation of hugo which has three maior effects: Increase the community of hugo to include those who are not that good in english; Gives an huge example of the power of hugos i18n and how it works; Increase the amount of people working on the documentation and trying to understand / translate it which will help finding holes in the english documentation which will lead to a more readable and more powerfull english documentation.

What I can do myself: Translate the documentation into german and participate in the programming. I just would be happy to have someone start migrate the content to i18n so I can join and help working on that, too.

3 Likes
2

I could also participate in programming and translate into russian.
Should we also translate the home page (hugodocs.info/)?

3
  1. The docs lives at gohugo.io
  2. hugodocs.info used to be @rdwatters own private dev site
  3. Translations are a good idea, but It would be very ineffective to start that job before @rdwatters site is finished/released
4

Of course we should translate docs after the release of new site.

5

Couldn’t we already start to initialize i18n? I do not see any conflicts there.

6

That would be awesome, @bogem.

Ugh. Hopefully not for much longer :smile:

Agreed.

@Fjolnir-Dvorak Thanks much for starting this thread. I appreciate your enthusiasm and willingness to help! According to the data, Germany is the third most popular country/region for Hugo users behind the US and UK, so I think everyone is grateful to have native-German speakers (@digitalcraftsman) as part of this community. I only wish I spoke the language. It would make my Oma a very happy woman.

That said, @bep makes a good point about holding off. There is some housecleaning–not the least of which is moving https://hugodocs.info and figuring out the workflow therein-- that still needs to be done before we start a one-to-one translation of the documentation.

Even after we move hugodocs.info to gohugo.io, here are some issues we need to address:

  1. Standardizing the doc content types and a proper content model
  2. Agreement on site architecture from the Hugo team
  3. Agreement on content management strategy; e.g.—a one-to-one translation of every file isn’t especially efficient. Instead, it’s better to reuse content when appropriate in the form of, e.g., snippets, signatures, etc. You’ll see how my readfile shortcode is a hack to try and get this functionality for things like the BlackFriday configuration, which I knew was going ot live in more than one location.
  4. Documentation that mirrors Hugo versioning; this will likely need to wait for Hugo v1.0
  5. Content strategy, and this is the most important part: we need to figure out who our audience is and define the scope/purpose of the documentation so that it doesn’t quickly balloon out of control.

This seems like a long list, but not everything on here needs to take a long time. For what it’s worth, when I restructured the content, I had i18n in mind. This is the reason sections like functions are built into separate files and we now have archetypes for almost every section.

If you have any more feedback on how I can improve https://hugodocs.info, please keep letting me know by submitting issues to GitHub - rdwatters/hugo-docs-concept: NO LONGER MAINTAINED. See the official Hugo docs at /gohugoio/hugoDocs or via Gitter, this forum, etc. You are more welcome to create a fork and start hacking away on translations, but I have to warn that you I make a lot of small copy changes and am still actively shifting areas of content based on user feedback, basically every day. I imagine this will continue for at least the next month.

In the interest of transparency, I can tell you that the content that needs the most help right now is the Quick Start, which would benefit greatly, IMHO, from a new Hugo default theme that’s been developed to showcase core Hugo principles and get users up and running quickly. (See this issue here for more context).

P.S. For reference, I’ve been digging into Vue.js a lot lately, and my goal would be to create documentation of that quality. It takes new users through a very smart, thorough, stepwise approach to learning the framework while being effectively structured for easy reference. I’m now convinced it’s the best FOSS documentation I’ve ever read. Just a thought


1 Like
7

I think translating the documentation is a wrong move.

(1) The translated documentation will need to be maintained, and the subset of Hugo users that speak a certain language and are willing to contribute is probably incredibly tiny.

(2) I doubt how helpful translated docs are when the forum is still English. If you cannot read English well enough, how would such a person benefit from the forum?

(3) There are a lot of nuances of translating a technical English documentation to another language, especially when people of that other language then in their head have to convert the translated documentation back to English when asking for help. I think that gives a lot of miscommunication on the forum with time and energy wasted talking past each other.

(4) Webdevelopers, Hugo’s target audience, already live in a world where English is the main language. While a translated Hugo documentation might help those not sufficient enough in English, they still have a lot of tools in their workflow with English-only docs (so still are required to go through English).

(5) One argument for translating the documentation is that it will help people “understand” Hugo better. I think understanding doesn’t necessarily depend on the language in which it’s written but rather how it’s written. If Hugo docs are all written with accessible English – like you’d hear on television – then the understanding might be better than if we try to translate complex, academic-like English into another language.

(6) Translating Hugo documentation can, ironically enough, be less inclusive. What if Bep decides to write an in-depth tutorial on Hugo in Norwegian? The quality of the English docs will be less compared to that Norwegian content, and then we’d need to find another Norwegian Hugo user that can translate that content into the English docs.

Or what if Rdwatters would be German and made all of his docs contributions in German? That would not even reach 5% of the usefulness of his current work. My point: the Hugo project will benefit the most if everyone contributes in English. And since other people can easily verify and check English articles (more possible eyeballs), that content is also easier to improve on even when the initial version was written by a non-native English speaker.

Just to clarify; English is not my primary nor secondary language and so am not biased that way. But speaking from a pragmatic standpoint, keeping the docs English only seems the most helpful to me.

1 Like
8

@Jura,I feel like an ugly American agreeing to the idea that documentation should only be in English.

That said, the strongest point you make is that Hugo has very limited staff, at least within the scope of a project like a website with hundreds of pages that would need constant translation. The current docs are strong and testament to the hard work of the community, but they’re disorganized. This complexity will definitely increase by an order of magnitude if we decide to translate in the future.

However, I don’t want to reduce the enthusiasm and goodwill of people like @bogem and @Fjolnir-Dvorak , so hopefully with these newer and more awesome versions of Hugo–and our guru, @bep, steering the development ship–the community will continually grow stronger and larger to the point where translation won’t be so daunting :smile:

The sections would be as follows:

  1. bier
  2. Oma
  3. Opa
  4. David Hasselhoff


and that’s about all the German I know. Worst documentation ever :laughing:

2 Likes
9

I think we should just do this once we get the new docs site live. I have no plans doing a Norwegian version, but I know having their own language is more important in some countries than others – and with the strong multilingual feature in Hugo, we can make the translation links very visible with emphasis on English as the canonical version. If the popularity of Hugo continue to grow, it is much better to have the information in “one place”.

1 Like
10

I thought of that problem to when writing this ticket. But what I think is more important (and more valueable) is, if someone is translating from a not foreign language he/she is reading the english documentation out of a complete different angle of view. For me it is much more easier to improve the original english documetation if I am trying to translate them and to explain them in my foreign language.
What I do not intent and hope that it will not grow in that way is, that the documentations are cared for seperate. And I think there are ways to go to bypass this problem without much of effort.

@Jura You are absolutely right. It is something that will happen if we will not look after it and think of it. But I also truely believe that the opposite is also valid.
@rdwatters There are so many problems in Hugo or/and so many things to improve. I do not think that a no could stop the enthusiasm

11

Maybe when Hugo is more feature-complete, some “how to Hugo” books can be written in other languages. I think it’s too large and chaotic a job to do it “live”.

2 Likes