Guide to Translating Field Kit ⚠️ EXPERIMENTAL!!

[jgaehring]

UPDATE

Since we are concentrating our efforts on Field Kit 2.0 at this point, the translation features in l10n will no longer be supported, at least in FK versions 1.x. Hopefully once we get to the 2.0 General Release, we can turn our attention towards finally completing #214, to have more stable and reliable translations going forward.

You can refer to #376 (comment) for the most recent changes that effect 1.x versions of Field Kit, but again, bear in mind these features will not be supported officially going forward.

---

As documented in #214, @rafaeltcc and I have begun an experiment to provide translations of Field Kit into Portuguese, with the possibility of translating other languages down the line. A few caveats:

• This is highly experimental. Expect translated versions to break and lag behind in updates. There is no guarantee of support, and versions may become deprecated with little notice. Use at your own risk.
• Contributing requires some familiarity with code and version control (git). A beginner's knowledge is probably sufficient, but there may be a learning curve and some headaches along the way.
• These translations are ephemeral and will ultimately be superseded by the farmOS/Drupal-based translations. We encourage most would-be contributors to add their translations there.

That said, if this sounds like a fun experiment to you and you want to get your feet wet in the JavaScript codebase w/o much previous experience, come on in!

Requirements and setup

You'll need a GitHub account and the following applications installed:

• Node.js
• Git
• a text editor (I recommend VS Code)

Once you have those installed, you'll want to clone this repository and install the dependencies:

git clone https://github.com/farmOS/farmOS-client.git
cd farmOS-client
npm install

Now, if you run,

npm start

and open http://localhost:8080, you should see Field Kit running!

But right now you haven't pulled any of the localization (l10n) code. That's hosted on my own fork, so stop the dev server with Ctrl + C and then you'll to need to add my remote and checkout that branch:

git remote add jgaehring https://github.com/jgaehring/farmOS-client.git
git fetch --all
git checkout l10n/pt

That will pull down the l10n code, with the Portuguese translations specifically. As we add other languages, there may be other language codes available for your preferred language.

Now when you restart the dev server (npm start), refresh the page, and open up the main menu, you should see options like this:

Great, now you can start adding translations!

Translating & Git workflow

We'll be using a special Git workflow for translating Field Kit, so we can make sure to share any work that's common to all languages, and keep . To do so, we need to keep changes that can be shared in separate commits from the changes that are specific to a language. Basically, any changes within the src/core/store/l10n/translations/ directory will be specific to a language, while any changes outside of that directory can be shared.

Wrapping strings with $t()

So we're assuming that the files you want to translate have not yet been wrapped in the special $t() function. Here's a simple example of what we mean:

<h2>{{ $t('Welcome to farmOS') }}</h2>

That wrapper function, as well as the single-quotes, ' ', make it possible for the phrase to be translated as a JavaScript string. Additional syntax is required depending on the context. Here, the string occurs in a block of HTML, between tags, so we need the double-curly-braces, {{ }}, as well. In other cases, the string might be the value of an HTML element's attribute, in which case the curly braces aren't needed, but the attribute name itself needs to be prefixed with a colon, :, like this:

<farm-toggle-check :label="$t('Share My Location')" />

Notice that we're differentiating the JavaScript single-quotes ' ' (inner) from the HTML double-quotes " " (outer). (Sidenote: this technically isn't HTML; rather, it's Vue's "Single File Component" syntax, but it's close enough. More info on that in their docs.)

If the string appears in a block of plain JavaScript, only the $t() wrapper is needed.

const msg = $t('Hello World!')

When you're done with these changes, you'll want to commit them before adding any of the actual translations. This way we can merge those commits back into the l10n/shared branch, and eventually merge it with the main develop branch in the farmOS repo. It will also mean that other translators won't have to duplicate your work of wrapping the English strings in $t() functions, and you can benefit from their work as well.

You can test that the changes didn't produce any errors by running the dev server, if you're not already. Translations won't appear on the screen, only the original English phrases, but at least you can be sure nothing broke while adding the $t().

If everything looks good, you'll first want to stage all the changes you want on the l10n branch and then commit them with a message that is prefixed with l10n: . You can do this from your editor's GUI controls, if it provides Git tools, or from the command line like this:

git add src/core/App.vue
git commit -m "l10n: Wrap strings in App.vue"

The prefix will make it easier to identify which branch the changes need to be pulled to, either the l10n/shared branch or the l10n/pt or other language branch; "l10n: " indicates a shared change, while "l10n/pt: " would indicate a Portuguese-specific change.

Adding translations to pt.js or other language file

If the strings in a file have all been wrapped in $t() functions, whether by you or a previous contributor, you can now start adding translations of those strings for your language.

Under the directory src/core/store/l10n/translations/ you will find a file for your language code, such as pt.js. When you open it you will see a JavaScript object literal as the default export. It will have a name property, and a strings property, the latter being a nested object literal containing the translation strings. Object literals are like dictionaries or maps in other languages; they're comprised of a simple key-value pair. The strings object will have a pairs where the key is the original English word, exactly as it is wrapped by the $t() function, and the value will be the translation of that phrase into the language you are providing. Importantly, the key is case sensitive, so it must be typed exactly the same as you found it in the source file. By convention, the strings are divided by comments, marking which file's translations are on the following lines, so as to make it easier to find a particular translation in the future. Here is what one such file might look like:

export default {
  name: 'Portuguese',
  strings: {
    // App.vue
    'Select Language': 'Selecionar o Idioma',
    'English': 'Inglês',
    'Portuguese': 'Portugues',
    // Home.vue
    // HomeMenuBar.vue
    // Login.vue
    // Logout.vue
    // etc...
  },
};

Note that we're only using single-quotes, ' ', in this file, which is the preferred style for our project, which uses the Airbnb JavaScript Style Guide. We ask contributors to adhere to this standard so our maintainers (eg, me) don't have to correct them all later in order to pass our linter.

If you're unsure what translation to use, please refer to the Drupal/farmOS translation base. It's always best to be consistent with the translations already being provided there. If you strongly disagree with the choices there, open a submission for correcting it through Drupal.

Once you've completed translating a file, it's a good time to commit that to git. You'll commit on the l10n/pt branch or the Portuguese translation, or the corresponding branch for your language, and add a prefix to the commit of "l10n/pt". So from the command line:

git add src/core/store/l10n/translations/pt.js
git commit -m "Translating App.vue"

And that's it!

Opening a Pull Request (PR)

Once you've completed translating several files, you may want to have those changes included in the main translation repo. To do so, you'll need to push the changes to your own fork and open a PR.

If you haven't yet created a fork, you can do so on GitHub. On the main repo's page you will see a "Fork" button in the upper right-hand corner. Click on that and fork will automatically be created for you. Then under your fork's page you'll see a "Code" dropdown which will allow you to copy the .git link to your clipboard. Then from the command line, in your local repo:

git remote add my_name https://github.com/my_name/farmOS-client.git

Now you can push to your fork:

git push my_name l10n/pt

Following that, go back to your fork's page on GitHub, change the branch from develop to l10n/pt in the dropdown menu, then click the Pull Request button. This will take you to a page for creating a pull request, but you'll want to change the "base repository" from farmOS/farmOS-client to jgaehring/farmOS-client. Add any notes you feel are relevant and then open the PR. The maintainer may have comments or corrections to propose, or may add a few commits of their own, but they should be able to merge your changes into the main translation repo within a few days.

Thanks for contributing!

[csersyadav]

git checkout l10n/pt
branch does not exists
where is latest code if i want to work on it

[jgaehring]

Hi @csersyadav!

Sorry, this post is grossly outdated!! Good news is, it's gotten a heck of a lot simpler.

I would recommend creating your own branch off the develop branch. Then it's just a matter of editing the translation file you wish to work on, or creating a new one. They're all located in src/core/store/l10n/translations, with the lang-code as the filename. So far just Portuguese and German. There are a few other quirks, but that's the gist. Are you looking to expand on one of those translations, or start with another language?

I'm happy to do a full walkthrough with you, or help out in any other way. 🙂

[csersyadav]

Thanks for replying
i am trying to add another language (Hindi) to the translations
how i can test it

[jgaehring]

For testing right now I think the only option is to run the development server in the browser. You'll need to have Node.js installed. Then you just need to cd into the project's directory and run:

npm install
npm start

That will start the development server, and you should be able to view the app at http://localhost:8080/.

To add your language, you'll first need to add language code and other details to enabledLocales here:

https://github.com/farmOS/farmOS-client/blob/684f19efbd3a0399292f0c3cf1cbafd1edaa2570/src/core/store/l10n/module.js#L4-L19

Then, assuming the language code is hi, in the src/core/store/l10n/translations directory create a file called hi.js. In that file, you want to create an object that looks like:

export default {
  name: 'Hindi',
  strings: {
    // your translations go here...
  }
}

For convenience, I would simply copy and paste the entire file from de.js or pt.js into hi.js. That way you'll already have all the strings in English that are already being picked up by the translator.

That's probably a good start for now. If you have any trouble, please let me know!

[csersyadav]

i have made this changes develop...csersyadav:develop
after this i did
npm install npm start

getting error in browser console

XML Parsing Error: syntax error Location: http://localhost:8080/farm.json Line Number 1, Column 1:

message in execution command line is
I Your application is running here: http://localhost:8080 [HPM] GET /farm.json -> http://localhost:80 Clearing cookie on GET request to /farm.json [HPM] Error occurred while trying to proxy request /farm.json from localhost:8080 to http://localhost:80 (ECONNREFUSED) (https://nodejs.org/api/errors.html#errors_common_system_errors)

application runs in but only in english and there is no option to change language

[jgaehring]

Do you have a local farmOS server running? Or are you connecting to an outside server?

[csersyadav]

i am not connecting to any server
i think this app also works offline and translation should not be affected by server sync feature
please let me know if its needed and how can sync to my hosted server

[jgaehring]

It does require a server for initial sync.

You can run a server on your local machine using these instructions:
https://farmos.org/development/client/#proxying-a-farmos-docker-container

Thanks for being patient with this process. I haven't had a chance yet to smooth out the procedures for adding translations yet because it's still very much experimental. If you'd like to find a time to go over this together in real-time, let me know. I'm thrilled you're making the effort to add another translation!

[csersyadav]

setup the docker dev environment on local now there is no error in network tab and console as well
but still only english no hindi

can you please send me link to branch which works with non english translations

[jgaehring]

Do you have translation enabled on your farmOS server?

[jgaehring]

You'll need to enable Hindi on your server:
https://farmos.org/hosting/localization/

[csersyadav]

It works now Thanks for help Offline client is not so offline and synchronisation is not optional

…

On Tue, Jan 12, 2021, 12:55 AM Jamie Gaehring ***@***.***> wrote: You'll need to enable Hindi on your server: https://farmos.org/hosting/localization/ — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#376 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABXS4SRECLHZDQEWNPK4H3DSZNGA5ANCNFSM4PU5C7IQ> .

[jgaehring]

That's correct. We're hoping to explore some truly local-first solutions in the future, but for now there are still some features that require an initial server-client connection before they will work offline.

Glad you got it working! If you'd like to open a pull request, we can probably merge it into the main deployment and release it to farmos.app and the app stores.

[csersyadav]

Sure I willl

…

On Tue, Jan 12, 2021, 7:38 AM Jamie Gaehring ***@***.***> wrote: That's correct. We're hoping to explore some truly local-first <http://inkandswitch.com/local-first.html> solutions in the future, but for now there are still some features that require an initial server-client connection before they will work offline. Glad you got it working! If you'd like to open a pull request, we can probably merge it into the main deployment and release it to farmos.app and the app stores. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#376 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABXS4SURRUFXH3NJTOD5SFLSZOVLHANCNFSM4PU5C7IQ> .

[jgaehring]

Closing. See my updated comment at the top.