Here is a quick start guide on how to improve help pages in the Jabref User Documentation.
The Jabref help pages are hosted at GitBook with integration to GitHub, which provides version control based on git. In order to edit or create a JabRef help page, you need a GitHub account. You can sign up here for free. If you already have an account, please make sure that you are signed in.
The easiest way to fix small errors, or to add additional information, is to edit a help page directly in your browser, using the following steps.
At the top of each help page, you can find the GitHub icon with "Edit on GitHub" link. Just click the link to show the source of the page.
This leads you to the GitHub page associated with the help page:
To actually edit the page, click on the pencil icon, as highlighted above.
The window to edit the page at GitHub looks like this:
Most text can be simply added/edited in this field as plain text. However, you can style your contribution by using markdown. Markdown is a rather easy way to format text without the need for complex markup, such as with HTML. You can find an introduction to markdown here or here.
In order to review your changes, click on the "Preview changes" tab:
To save the changes, create a so-called "Commit" by scrolling down and pressing the "Propose File Change" button:
Please note: The message you provide here will be visible in the history of the help page, so please consider your change and provide a meaningful description of your changes.
As the last step, submit the changes you have made back to the JabRef team:
Just press the "Create Pull Request" button, and confirm the creation of the request on the next page.
That's it! The JabRef team will review your changes and publish them on docs.jabref.org.
To edit more than one file at a time, add screenshots, and for other more advanced changes, we recommend that you checkout this repository locally and create a Pull Request of your changes using the standard git and GitHub workflow.
The best way to enter tables is to use this Table Generator for Markdown. It has the nice feature to generate markdown tables from different sources, e.g. you can directly copy the table from a spreadsheet or upload a csv file. Just copy and paste the generated markdown into the documentation.
We are really happy that you are interested in contributing to JabRef. Please take your time to look around here. We especially invite you to look into our where members introduce themselves.
JabRef comes with a set of translations into 20 different languages: Chinese (simplified), Danish, Dutch, English, Farsi, French, German, Greek, Indonesian, Italian, Japanese, Norwegian, Persian, Portuguese, Portuguese (Brazil), Russian, Spanish, Swedish, Tagalog, Turkish and Vietnamese.
If the JabRef interface already exists in your language, you can help improve it. Otherwise, you can start translating JabRef into your own language.
We use the service of Crowdin to keep our translations updated. It is a service directly running in the browser and one can quickly join and start translating.
Visit https://translate.jabref.org/ to get started
Select your preferred language, login, and click on JabRef_en.properties
Choose the string you want to translate in the left panel (strings to be translated are listed first)
and enter the translation in the central panel (suggestions are given at the bottom)
Crowdin offers to quickly add a new language. Please contact us so that we add a new language for you.
You may decide to wait for a new test version of JabRef to be published.
To test directly your translation, you must be able to compile the source tree after making your additions. This requires you to install the Java Development Kit. Ensure that you use the most recent version.
Crowdin allows for downloading the current translation file:
Place the downloaded file in the path src/main/resources/l10n
. Then, execute gradlew run
in the root directory and JabRef should start.
For a new language to be available within JabRef, a corresponding line must be added in the Java class GUIGlobals (found in the directory /src/main/java/org/jabref/logic/l10n/Languages.java
in the JabRef source code tree). The line is inserted in the static {}
section where the map LANGUAGES
is populated. The code must of course be recompiled after this modification.
For each language, there is the file JabRef_xx.properties
(xx
denotes the country code for the language). It contains all translations in a key/value format. In the JabRef source code tree, the property files reside in the /src/main/resources/l10n directory.
Each entry is first given in English, then in the other language, with the two parts separated by an '=' character. For instance, a line can look like this in a German translation file:
Note that each space character is escaped (\
) to make it a valid property key. The translation value does not need any escapes.
Some entries contain "variables" that are inserted at runtime by JabRef - this can for instance be a file name or a file type name:
A variable is denoted by %0
, %1
, %2
etc. In such entries, simply repeat the same notation in the translated version.
As we can see, there are several "special" characters: the percent sign and the equals sign, along with the colon character. If these characters are to be part of the actual text in an entry, they must be escaped in the English version, as with the colon in the following example:
The character encoding should be UTF-8. Please avoid Unicode escaping such as \u2302
.