Andras/BoundlessFlowCampus2K

Fork 0

A localization JSON standard is required. #880

New issue

Closed

opened 2026-05-11 10:31:33 +00:00 by f21marfo · 6 comments

f21marfo commented

2026-05-11 10:31:33 +00:00

Collaborator

In particular is the problem that JSON files by their very nature do not support comments, also the language/translation system we are using requires a flat JSON, which means no nested hiearchy. These issues makes grouping very difficult and risks becoming an unreadable mess.

I would personally suggest the use of namespaced keys, with the page/component as the root namespace and additional namespaces for subsections where suitable. And I would suggest using linebreaks to group pages/component keys.

Here's an example of what the localization keys for the settings page would looke like.

en.json
{
	"settings.settingsTitle": "Settings",
	"settings.account.accountTitle": "Account",
	"settings.account.displayName": "Display Name",
	"settings.account.email": "E-mail",
	"settings.account.password": "Password",
	"settings.preferences.preferencesTitle": "Preferences",
	"settings.preferences.language": "Language",
	"settings.preferences.notifications": "Notifications",
	"settings.privacySecurity.privacySecurityTitle": "Privacy & Security",
	"settings.privacySecurity.2FA": "Two-Factor Authentication",
	"settings.privacySecurity.deleteAccount": "Delete Account",
	"settings.application.applicationTitle": "Application",
	"settings.application.defaultPage": "Default Page",
	"settings.application.accessibility": "Accessibility"
}

sv.json
{
	"settings.settingsTitle": "Inställningar",
	"settings.account.accountTitle": "Konto",
	"settings.account.displayName": "Visningsnamn",
	"settings.account.email": "E-Post",
	"settings.account.password": "Lösenord",
	"settings.preferences.preferencesTitle": "Preferenser",
	"settings.preferences.language": "Språk",
	"settings.preferences.notifications": "Avisering",
	"settings.privacySecurity.privacySecurityTitle": "Sekretess och Säkerhet",
	"settings.privacySecurity.2FA": "Tvåfaktorsautentisering",
	"settings.privacySecurity.deleteAccount": "Ta bort konto",
	"settings.application.applicationTitle": "Applikation",
	"settings.application.defaultPage": "Startsida",
	"settings.application.accessibility": "Tillgänglighet"
}

Before I proceed any further on #861 i would like this matter sorted. Thank you!

In my work with coming to grips with issue #861, i have come to the realization that we at present have no standard for localization keys, which I think is vitally important to have since all non-user text will rely on them to print text. In particular is the problem that JSON files by their very nature do not support comments, also the language/translation system we are using requires a flat JSON, which means no nested hiearchy. These issues makes grouping very difficult and risks becoming an unreadable mess. I would personally suggest the use of namespaced keys, with the page/component as the root namespace and additional namespaces for subsections where suitable. And I would suggest using linebreaks to group pages/component keys. Here's an example of what the localization keys for the settings page would looke like. ``` en.json { "settings.settingsTitle": "Settings", "settings.account.accountTitle": "Account", "settings.account.displayName": "Display Name", "settings.account.email": "E-mail", "settings.account.password": "Password", "settings.preferences.preferencesTitle": "Preferences", "settings.preferences.language": "Language", "settings.preferences.notifications": "Notifications", "settings.privacySecurity.privacySecurityTitle": "Privacy & Security", "settings.privacySecurity.2FA": "Two-Factor Authentication", "settings.privacySecurity.deleteAccount": "Delete Account", "settings.application.applicationTitle": "Application", "settings.application.defaultPage": "Default Page", "settings.application.accessibility": "Accessibility" } sv.json { "settings.settingsTitle": "Inställningar", "settings.account.accountTitle": "Konto", "settings.account.displayName": "Visningsnamn", "settings.account.email": "E-Post", "settings.account.password": "Lösenord", "settings.preferences.preferencesTitle": "Preferenser", "settings.preferences.language": "Språk", "settings.preferences.notifications": "Avisering", "settings.privacySecurity.privacySecurityTitle": "Sekretess och Säkerhet", "settings.privacySecurity.2FA": "Tvåfaktorsautentisering", "settings.privacySecurity.deleteAccount": "Ta bort konto", "settings.application.applicationTitle": "Applikation", "settings.application.defaultPage": "Startsida", "settings.application.accessibility": "Tillgänglighet" } ``` Before I proceed any further on #861 i would like this matter sorted. Thank you!

f21marfo added the

help wanted

project documentation

frontEnd

labels

2026-05-11 10:31:33 +00:00

c24danli commented

2026-05-11 11:40:13 +00:00

Collaborator

Good insight! as this is the first real implementation of our localization we are a bit behind on the documentation.
We believe your suggestion is a good way to go about it.

I would personally suggest the use of namespaced keys, with the page/component as the root namespace and additional namespaces for subsections where suitable. And I would suggest using linebreaks to group pages/component keys.

We could remake it to have a locale file for each view/component but as most of our views have very little printed text it felt like it would just bloat the code.

Start using the suggested method of using namespace with line brakes to make the code more readable,
we will create issues to update the wiki for how to implement the localization along with adding it to the review template. But i think you can start with the implementation, that way if you find any problems or changes we need to do we can have that in mind when creating the wiki for implementing it in the future.

Does that sound good to you @f21marfo?

Good insight! as this is the first real implementation of our localization we are a bit behind on the documentation. We believe your suggestion is a good way to go about it. > I would personally suggest the use of namespaced keys, with the page/component as the root namespace and additional namespaces for subsections where suitable. And I would suggest using linebreaks to group pages/component keys. We could remake it to have a locale file for each view/component but as most of our views have very little printed text it felt like it would just bloat the code. Start using the suggested method of using namespace with line brakes to make the code more readable, we will create issues to update the wiki for how to implement the localization along with adding it to the review template. But i think you can start with the implementation, that way if you find any problems or changes we need to do we can have that in mind when creating the wiki for implementing it in the future. Does that sound good to you @f21marfo?

f21marfo commented

2026-05-11 11:47:39 +00:00

Author

Collaborator

@c24danli Sounds good! I shall press on with the work.

f21marfo commented

2026-05-11 12:00:06 +00:00

Author

Collaborator

Like:

	"UI.edit": "Edit",
	"UI.update": "Update",
	"UI.change": "Change",
	"UI.delete": "Delete",
	"UI.manage": "Manage",
	"UI.setup": "Setup",
	"UI.adjust": "Adjust"

Also just to add, for reference, i realized a separate "UI" category/namespace would probably be good to have, for non-unique strings like: Edit, Change, Update, Delete, etc. Kind of pointless to translate them multiple times. Like: ``` "UI.edit": "Edit", "UI.update": "Update", "UI.change": "Change", "UI.delete": "Delete", "UI.manage": "Manage", "UI.setup": "Setup", "UI.adjust": "Adjust" ```

c24danli commented

2026-05-11 12:15:41 +00:00

Collaborator

@f21marfo wrote in #880 (comment):

Also just to add, for reference, i realized a separate "UI" category/namespace would probably be good to have, for non-unique strings like: Edit, Change, Update, Delete, etc. Kind of pointless to translate them multiple times.

Like:
	"UI.edit": "Edit",
	"UI.update": "Update",
	"UI.change": "Change",
	"UI.delete": "Delete",
	"UI.manage": "Manage",
	"UI.setup": "Setup",
	"UI.adjust": "Adjust"

Yes for common things can it be a good idea to have this to reduce duplicate code. But if some views happens to have the same text then i would say it probably better to separate it just to have the flexibility to change just one.

@f21marfo wrote in https://git.webug.se/Andras/BoundlessFlowCampus2K/issues/880#issuecomment-9615: > Also just to add, for reference, i realized a separate "UI" category/namespace would probably be good to have, for non-unique strings like: Edit, Change, Update, Delete, etc. Kind of pointless to translate them multiple times. > > Like: > > ```text > "UI.edit": "Edit", > "UI.update": "Update", > "UI.change": "Change", > "UI.delete": "Delete", > "UI.manage": "Manage", > "UI.setup": "Setup", > "UI.adjust": "Adjust" > ``` Yes for common things can it be a good idea to have this to reduce duplicate code. But if some views happens to have the same text then i would say it probably better to separate it just to have the flexibility to change just one.

c24danli referenced this issue

2026-05-11 12:22:14 +00:00

Wiki documentation for localization standard #891

f21marfo commented

2026-05-11 13:13:57 +00:00

Author

Collaborator

@c24danli Oh definitely, that was more focused on unformatted monosyllabic strings, which are extremely unikely to change and remain consistent, regardless of context.

c24danli referenced this issue

2026-05-15 06:39:08 +00:00

Wiki documentation for localization standard #891

c24danli commented

2026-05-18 12:44:45 +00:00

Collaborator

This is added to the wiki so i will close this issue

c24danli closed this issue

2026-05-18 12:44:46 +00:00