Skip to content

Home

Jump to bottom
Robert Korulczyk edited this page May 3, 2021 · 8 revisions

This guide describes how to use this template. But before you create new language pack, make sure that there are no existing and maintained language packs for your language - there is no point in creating multiple concurrent language pack for the same language, it is better to focus on creating one complete language pack.

This guide will assume that you will use Weblate for translation. While you can use this template without Weblate, this guide will not cover this use case.

1. Creating GitHub repository

Language packs are Composer packages. In order to create such package, you need to create git repository (usually hosted on GitHub). You can do this by clicking "Use this template" button in this repository.

As repository name you can use format flarum-lang-xxish, where xxish is textual name of your language (like "polish" or "english"). Make sure that your repository is public, so other people will be able to use your package.

Now you have your git repository with basic template files.

2. Template adjustments

After creating repository from template, you need to edit some files to adjust template for your extensions. There are some conventions that may help you find string that need to be adjusted:

  • xxish should be replaced by textual name of your language (like polish or english). Case matters, so Xxish should be replaced by capitalized name of your language (like Polish or English).
  • xx should be replaced by ISO 639-1 code of your language (like pl or en). If you want to target specific dialect, you can add an underscore followed by an ISO 3166-1 alpha-2 country code (for example en_US for "English (United States)").
  • your is usually used in places where you should place information about you, so Your Name should be replaced by your actual name, and [email protected] by your actual email address.

Cloning repository locally and using some IDE may be the most convenient way of replacing these strings, but if you don't have any advanced editor or don't know how to use git, you may do this directly in GitHub in your browser, by clicking "Edit this file" icon.

Bellow you can find detailed instruction which files and how should be adjusted.

2.1. LICENSE

First, replace Robert Korulczyk <[email protected]> in LICENSE file by your name and email. You can skip email part if you don't want to share your email in this way - your name or nick should be enough.

2.2. icon.svg

Find square icon in SVG format for your language and save it as icon.svg in root of your repository. You should be able to use one of these flags.

On GitHub you can upload files using Add file -> Upload files option.

2.3. locale/config.js

This file should contain dayjs translations. Fortunately dayjs is already translated for most of languages. If you can find your language here, you can use these translations in your language pack. In order to do this, you should:

  1. Go to locale/config.js and replace all occurrences of xx by ISO code of your language.
  2. Read TODO comment and replace it by content of file linked in comment. Make sure you use correct language code - for some languages dayjs may use different convention (for example en-us instead of en_US).

As a result file should look similar to this.

2.4. composer.json

composer.json is a JSON file containing your Composer package meta data. You need to follow JSON format rules while editing this file, since JSON does not forgive any minor mistakes (like trailing comma) and Packagist will reject any package with invalid JSON. You may use this tool to validate and automatically fix some minor mistakes.

Fields you should edit:

  1. name - this is full name of your package. It contains vendor name and project name separated by / - this name will be used while installing or updating your extension. You need to replace xxish by lowercased textual name of your language, and yourname by your vendor name. The name must be lowercased and consist of words separated by -, . or _. While it is not necessary, it is good to keep your vendor name in sync with your GitHub username. It also needs to be unique - Packagist will not allow you to publish package with vendor name, that is already used by someone else - you may want to use search to ensure that name you pick is available.
  2. description - replace Xxish with textual name of your language.
  3. homepage - replace it with link to your GitHub repository.
  4. authors - replace available fields with information about you. You can remove email and homepage sections if you don't want to share these information, but remember to remove trailing comma from last element in this array. You may also link to your GitHub profile as homepage.
  5. support - adjust URLs to link to your GitHub repository.
  6. extra - replace Xxish by textual name of your language, and xx with language code. You can also fill flagrow.discuss with link to discussion about your language pack on official forum (you can fill that field later - you need to publish package first before you will be able to announce it on forum).

2.5. README.md

This file should contain basic information about package and how to install/update it. In order to adjust this file:

  1. Remove everything above --------- line (including line itself).
  2. Replace all occurrences of Xxish with capitalized textual name of your language (like Polish or English).
  3. Replace all occurrences of yourname/flarum-lang-xxish with your package name (name field from composer.json).
  4. Replace all remaining occurrences of xx with your language code.

It may be also a good idea to translate this to your language.

Clone this wiki locally