[James Ross]

In an effort to write down more guidelines and helpful information for people writing code for Open Rails, we have added a new document to the repository: Open Rails Code Guidelines.

This document is linked from within the General requirements section of our main Contributing to Open Rails document.

The first area covered by this document is logging - with guidelines on how to choose the right severity, log message, and method to call.

Please let me know if there are other areas of coding that you'd like to see documented guidelines for or if there is anything that can be improved with the new logging guidelines.

[C44-9W]

I think a similar guide for error messages in message boxes would be useful.

In particular, should catalogue lookups be on the message itself or on a message token?

With a token, we can make minor changes to the message without breaking all existing translations. On the other hand, it might be better to show the English message than a stale translation.

PS: This was prompted by the following message (from a PR review): "Failed to access the content repository (check Internet connection); automatic download not available. Error: {0}"

[James Ross]

C44-9W, on 24 October 2025 - 04:03 PM, said:

I think a similar guide for error messages in message boxes would be useful.

In particular, should catalogue lookups be on the message itself or on a message token?

With a token, we can make minor changes to the message without breaking all existing translations. On the other hand, it might be better to show the English message than a stale translation.

PS: This was prompted by the following message (from a PR review): "Failed to access the content repository (check Internet connection); automatic download not available. Error: {0}"

We have just added some guidelines on translations, which states "Use English (United States) for all translations" (I admit that could be clearer what it is talking about).

The catalogue lookup value is used for untranslated or partially translated languages, so it must be valid for displaying to the user. This also avoids the extra work and chance of messing up when using tokens (I have worked on projects using tokens).