As I mentioned in this thread, I think giving Flarum a translation UI might not be a bad idea after all. Here's why:
(Warning: this is going to be another long one!) 😛
Provide translators with more information
As I got to work on the translation keys, it occurred to me how important they can be to translators. Since a simple word or phrase can often be used with several different meanings, the translator may need some clues as to how the word or phrase is being used by the software in order to render it appropriately. The keys have to provide those clues, or at least an indication as to where the translator can look for the clues he needs.
So, to the extent that this is possible, @Toby is quite right to want the keys named in a more consistent manner. But there's a limit to how much info we can stuff in the those names. Say you find the following string in a YML file:
Is it being used as a verb, in a button that starts a recording process? Or is it being used as a noun, as a header for a list of database records? Where should we look for the answers to these questions?
This is a rather extreme example, and not one we're likely to see in Flarum. But it illustrates how important the key names can be, and how hard it is to make sure they contain enough info to be useful. Oh, we could add a preface to indicate where the key is being used. Or maybe a suffix that says whether it's a button or a header. Or heck, why not both? But if you start doing this on a case-by-case basis, you lose the consistency. And if you aim for consistency and rich information, you end up with monstrosities instead of key names. Where does it all end?!
A translation UI can offer an alternative way of providing translators with the information they need. In addition to the translation key, the original string (for reference), and a text box for the translation, the UI could also show:
- The path to the YML file the string is found in -- (more about this later)
- A listing of the code files that use the string
- A natural language description of where the string is used in the UI
- Notes indicating the sense in which an ambiguous string is being used
It's not uncommon for applications with built-in translation UIs to include the first item on this list. But translators are generally left to find the second item based on the first. And as for the third and fourth ... well, good luck finding that sort of thing anywhere. (Though this may have changed recently, I'm not all that up to date.)
Of course, a translation UI wouldn't be the only way to accomplish this. We could probably come up with a scheme for adding more info to the YML file by means of extensive commenting. But that could complicate things for those who want/need the YML to be as clean as possible, and it wouldn't exactly be a user-friendly solution for translators who aren't coders. With a translation UI, we could get the info from a separate "language resource documentation" file. That would put everything the translator needs right on the screen, while leaving the YML file clean for those who prefer it that way.
Time for a sanity check. Fortunately, thanks to Flarum's minimalistic approach to the use of language in the UI, there isn't likely to be too much confusion as to where a string is used, or what it means. A translator generally won't have to look very far to find the necessary information. So if this were the only reason I had for suggesting the creation of a translation UI, I probably wouldn't even bother. But if this stone can kill another bird or two, then maybe it might be worth tossing. (Yeesh! Who thought up that idiom, I wonder?)
Consolidate and ease access to language resources
It seems like most forum scripts these days offer some sort of translation UI, and tout this as a sales point. Flarum, on the other hand, is taking the road less traveled: go in and edit the files directly.
At first I didn't have any problem with this, as I was envisioning something like the esoTalk localization experience. Even without a UI, esoTalk is a breeze to translate. You can find nearly all the strings in one file! The only exceptions are seven little strings used by the BBcode extension, and their file is in the same folder. So even a translator with relatively little technical background can locate all the resources and whip out a translation with very little fuss.
The translation process for Flarum, by contrast, is starting to look rather more complex. Much of what was treated as core functionality in esoTalk is being moved to extensions, and the language resources are following them, so they aren't all in one place. There are good reasons for these changes, but they can tend to make the process a bit more intimidating for some of our translators, which is something we should avoid if possible.
It can also complicate the process of maintaining language resources. Let's say you notice a spelling error in a string and want to make a quick change. Before you can open the file and make the change, you first need to remember which file the string was in. A translation UI would put access to all those files in one spot (and presumably it would have a Search function to help you find strings in any file), so you're only a click or so away from making the change ... even if you're away from home and accessing on a mobile device.
Simplify the language pack creation process
If the translation process is likely to seem somewhat more intimidating to less technically-oriented translators, then using GitHub to get started will be an even greater hurdle. It seems to me that the process of creating a language pack could be handled by the translation UI. It could perform the necessary processing, or at least serve as a user-friendly frontend that will allow translators to get started from the comfort of their admin control panel.
Further, once the Marketplace is going, the translation UI could also link into that, allowing translators to make their completed language packs available to everyone with just a couple clicks. Basically, I envision the translation UI as a central location from which a translator can accomplish any task related to the l10n process ... with the exception of looking up words in a dictionary.
Incidentally, I don't think there's any reason to make a translation UI available as a default bundled extension. Even if it created as a first-party extension, it will be sufficient to make it available on the Marketplace. Admins who just want to install a language pack (to say nothing of those who don't!) shouldn't be forced to deal with it.
Implications for the key naming process
Just to get back briefly to where we started: providing translators with a translation UI that offers richer information about the resources they're translating will take some of the pressure off the key names themselves. I wouldn't say we don't have to bother reorganizing the keys and making them more consistent; but we would probably be able to get by with shorter key names that, by themselves, wouldn't be so helpful to translators.
PS: Just so I'm not misconstrued: I'm not saying anyone should start working on the extension right away. But if we know it's coming down the road, we can keep that in mind as we talk about keys now.
