Adapting and localizing Tryton and other free, open source accounting software for your country

I previously wrote a comparison of free, open source accounting software. Most of these applications only come with a generic Chart of Accounts and no support for tax reporting. This makes them suitable for personal finances and small volunteer groups. For many freelance workers, consultants and small businesses, it is now essential to have some basic tax reporting.

Tryton is one of the few packages that is now addressing these needs. The Tryton modules directory includes five official localizations with a business-ready chart of accounts and tax codes. A discussion in the forum reveals more countries coming soon.

I had a look at how to add more, starting with Switzerland and I'm sharing my observations here for anybody else who wants to try this. The procedure described here is valid for any accounting software but I give examples with Tryton.

Share your progress, find collaborators

To avoid duplication, it is a really good idea to search the forum and search the bug tracker to see if anybody else is working on the same country. If you are first, you can publish an announcement in each of these places so other people can find you.

Many hands make light work.

Translation of the user interface

Translation of the user interface into your local language is independent from the localization effort. For example, if you have a team of five people sharing the workload, three people could work on translation while two people work on the chart of accounts and tax codes.

People who want to translate Tryton can find details here. Please open a bug asking for your language to be added to the list for contributions. Here is an example of how to file the bug report to begin adding your language.

Research your localization, share the links

Before starting, it is a good idea to find all of the following and create links to them from the forum topic or bug tracker for your country:

1. Example chart of accounts for your country, preferably in CSV format, see the examples I found for Switzerland
2. Any key document explaining your chart of accounts, notes are included in the Swiss PDFs above
3. If your country has VAT, GST or a similar consumption tax, obtain a copy of the VAT return form, Swiss example here.
4. Any guidance notes that help explain the VAT return form, in the same directory as the last example
5. if your country has automatic, electronic submission of tax reports, obtain a copy of the specification, for example, an XML XSD schema file and supporting documentation. The Swiss eCH-0217 documents are copied here.

Create Chart of Accounts in a CSV, add columns for Tryton

I created a short script that converts a CSV file into a Tryton XML file. This makes it easy to edit the initial draft Chart of Accounts in a spreadsheet. You need to edit the script to include your CSV filename and list of languages.

Please see all the columns used in the Swiss Chart of Accounts spreadsheet here. The script needs all these columns. You can add the account names in multiple languages, simply add an extra column for each language.

Save or export your spreadsheet as a CSV. Run the script to process it.

Explore the tax code tree for one of the supported countries

It is a good idea to create an empty database using one of the supported countries, for example, France so that you can see what the finished result looks like. Look at the tax code tree on-screen and compare it to a copy of the French VAT return form. Try to understand how the tree heirarchy relates to the form structure.

Here is the Swiss example:

Draw a tax code tree for your country on paper

This helps you visualize the result you are aiming for. You can see the Swiss VAT form here and you can see the tree drawing here. Compare the tree drawing to the screenshot above.

Notice the Swiss VAT form has three sections and each one is a different subtree. They don't easily combine into a single tree. The circled numbers (1), (2) and (3) in the drawing correspond to the sections of the form.

It is a good idea to share this diagram so other people can see how you designed the tax codes.

Begin creating the tax.xml file

If you look at one of the existing countries, for example, the XML file for French taxes, it may appear quite intimidating. It is 3,629 lines.

If you go about it in the right order then it becomes manageable.

1. Create the account.tax.group records first. France, Switzerland and other existing examples four of those, you can cut and paste them.
2. Create the account.tax.template records. These describe the rates, usually percentages, for each tax level. Create them in groups like the French and Swiss examples. Looking at the examples, you will see some old tax rates are there with the date for changing the rate. You don't need to create records for past tax rates if more than a year has passed since they changed. You do need to create entries for any new rates that will commence in the near future.
3. Create the tree structure using the account.tax.code.template records. In the examples, you will see each account.tax.code.template has some account.tax.code.line.template. Don't create those yet, just create account.tax.code.template to describe the tree structure.
4. At this point, you could load the XML into Tryton to see how the tree structure looks on screen.
5. Finally, add in the account.tax.code.line.template records for each account.tax.code.template. This is the most tedious part of the process. You can use <field name="amount">base</field> to sum the pre-tax values of sales and use <field name="amount">tax</field> to sum the tax amounts from invoices.

Here are the steps from the original document, the tree drawing, the XML and the final view: