We have moved our forum to GitHub Discussions. For questions about Phalcon v3/v4/v5 you can visit here and for Phalcon v6 here.

Multilingual documentation needs to go


It may sound controversial, but I think it's time to just remove multilingual docs.

Easier learning = bigger popularity of framework.

Part of learning process is actually searching for the answers. Searching for the docs. After new version of documentation came (don't remember, it's 1 or 2 years now since?) for me finding anything means just pain. I'm using multiple programming languages and cannot just remember full Phalcon API. Sometimes I need to look up even for simplest things, like "Textarea".

Look what I get:



Wasted time. These other-lanaguage docs are never complete anyway. One paragraph in Polish one in English. At the same time indexing of them just sucks, don't work. Why I get JP docs (empty) at the top is other thing. Have no idea. I only drive a Honda lol.

I don't have time to help, was only backing with couple of $ to help at least that way. Currently I need money but in future I will continue doing it, for sure.

What I vote for is:

  1. Remove all languages - Programmer who don't use english isn't programmer at all (as programming apis use english anyway),
  2. Redirect all to EN version so it will fix indexing,
  3. Create new search on-site (if you have time some day, I know it's not that easy),
  4. Rename all Documentation titles from "Class Phalcon\Cli\Console" to "Console (and smaller font: Class Phalcon\Cli\Console)". It should help in proper indexation. Google cannot read, remember.

I know there was some topic about it already. I just wanted to say that it's getting worse every month instead of improving.


I've had this same thought. I think it would be a different matter if the different translations were complete, but they're not. They're almost embarassingly incomplete.

Emphatic +1.

With that said, this will probably get more traction if you post it in the repository for the documentation: https://github.com/phalcon/docs


I think multilang can be helpful especially chinese or japanese. But they should be only indexed when translated. Maybe for the time beeing we should only allow the search engines to index en.

edited Jul '19

Any multilingual translation can be helpful, but are translations that aren't even close to complete helpful?

You make a good point about only allowing indexing on fully translated versions. But translation has been possible for a few years now and no language is close to complete.

I'd argue (and I think OP is arguing too) that it's wasted effort. The translations simply aren't being done - much less at a speed that is keeping up with development - so just cut the losses and turn them off.

The new documentation will definitely be much more helpful than Google. With the v4 documents we have integrated Algolia to help you find what you need faster. You will need to use the search box at the top

Also we have taken advantage of HTML5 element IDs to create self anchors in each document to help with SEO as well as navigation and change the titles accordngly to relfect better SEO

As for the multilingual documents and Google, I don't know. I have found myself in the same situation trying to read something in Portuguese when going from Google. Not sure why they do this.

Have a look at a finished document here: https://docs.phalcon.io/4.0/en/cache and give the search a try. It will become much better when we finish all the documents.


Before I go to SEO things I want to go back to this important question "Can multilang be helpful?". You say yes, IF done proper. Actually just in one way, because you may not need to read English paragraphs then. WELL MAYBE YOU SHOULD BECAUSE LEARNING IN IT IS ALL ABOUT ENGLISH lol :)

I will ask, "Can multilang be harmful?".

I say of course. In number of ways. It will be harmful for learning process, for framework 'look' (outdated or left docs are never a good sign), for developing process (wasting time), and for professionals too, who want to quickly check something and end up on Portuguese article.

But must important - some people actually translate Service names, Classes, or PHP language properties. It mixes and makes searching later harder. At the same time other person think that even "Services" keyword shouldn't be translated. At the same time languages are different, will this Search box at top work with non-english phrases?

We have 2019. Everybody can learn English to Docs-Reading level. Especially programmers. Even if Phalcon has Polish docs, I'll probably end up on English docs on Git, JavaScript, MySQL, Mail library, other library and on. In Poland many SAAS providers don't even make Polish docs. :)

Yes, 4.0 and search on top should be better. Unfortunately if I write "Forms" I still get 4 results:

  1. sr-sp (at top even that i'm on en/installation)
  2. en
  3. pt-br
  4. th-th

As far as my SEO knowledge go. Most important for google is link. Second are titles and headings. Third is text. Then are all website attributes (link 'lang'). If we make multilingual website but keep the same english article on every page, google will choose "most important" website randomly, probably where it gets first, and give it a best rating.

On every english page you have menu to switch language. They are all links. If we remove links and for example add <form><select> instead you remove this "index also different pages, maybe they are more important".

But on every other language (ja-jp) there should be link to main EN docs, so every time google is indexing ja-jp it's indexing EN too.

Main articles (like installation) will index good. But API Classes are as much important or even more. If we want them to be usable from search indexes too, we need to change link names and H1 titles on every page, like I wrote on top.

Search engines may see "Textarea" and "Forms/Element/TextArea" as a different phrase. That's why I suggest that you need to change links from "https://docs.phalcon.io/4.0/en/api/" and all Titles on every pages to "PHRASE first NAMESPACE second" => "Textarea <small>Forms/Element/Textarea</small>"

After some time if I search in google Phalcon Textarea I should find it :) If Docs backend is on github I can suggest proper changes.

But basically you could just remove languages, or disable for like 6 months to see how users and search engines will react. But don't forget to create .htaccess redirection to english.

Thanks for showing interest.

If you don't want to remove multilanguage documentation, you should probably look into this: https://support.google.com/webmasters/answer/182192?hl=en That would help you in preventing every language to show up for everyone.

Alternatively, I would suggest only allowing the english version to be indexed, and let the language setting be remembered via a cookie on the browser (with an automatic redirect to the selected language).

That way the search results become less of a mess, and you're still allowing the user to change the language of their documentation.