Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Suggestions for renaming of Localization related fields #39

Closed
BraedonWooding opened this issue Apr 11, 2017 · 6 comments
Closed

Suggestions for renaming of Localization related fields #39

BraedonWooding opened this issue Apr 11, 2017 · 6 comments

Comments

@BraedonWooding
Copy link
Member

Issue by koosemose
Saturday Feb 04, 2017 at 05:50 GMT # Sample: Friday Sep 13, 2013 at 22:58 GMT
Originally opened as TeamPorcupine/ProjectPorcupine#1775


Currently the localization related fields are LocalizationCode for name, and UnlocalizedDescription, which feels inconsistent, and in the case of the first a bit obtuse, and the second just a little awkward sounding.

In my inventory localization, due to momentarily forgetting what names were already in use, I used LocalizationName and LocalizationDescription, which are more consistent, and seem more obvious and direct. I suggest we change to these names (or if anyone else has better suggestions, then those).

Additionally, there are a few related functions which seem a little awkward, the one I recall is, I think, GetName, which @dusho pointed out. Perhaps GetName should return the localized name (so GetName on an o2 gen would return "Oxygen Generator" (or whatever's appropriate for the language) rather than "oxygen_generator", and have a matching GetDescription, and leave getting the unlocalized form to the Properties.

@BraedonWooding
Copy link
Member Author

Comment by BraedonWooding
Saturday Feb 04, 2017 at 07:42 GMT # Sample: Friday Sep 13, 2013 at 22:58 GMT


Now since this is localization I have a few little tid bits that I want to address (these are all to do with the fact the .lang files are a mess), first is that the localization files should have more extensive parser that allows for comments (so we can do some basic regions at least). However, we should also have multiple sections to allow overlap of key names. That is maybe there is an item section, a settings menu section...

This means that it's just cleaner (which is really needed as it grows), now on your points I think those names are both good and I agree with basically saying if you want non-localized you have to work for it (no function).

@BraedonWooding
Copy link
Member Author

Comment by koosemose
Saturday Feb 04, 2017 at 09:45 GMT # Sample: Friday Sep 13, 2013 at 22:58 GMT


Though I'm likely as bad as everyone else, I will remind you to try to keep on topic of the issue, mostly because unrelated discussion tends to get lost, so we end up discussing a thing and when the main point of the issue is resolved (so the localization names in this case), the issue is closed and now what has been discussed regarding the tangential things is often lost without any direct representation in the issues. And of course the more off-topic discussion there is, the less people pay attention to the primary point, and it either ends up unresolved or takes forever to resolve.

@BraedonWooding
Copy link
Member Author

Comment by BraedonWooding
Saturday Feb 04, 2017 at 09:46 GMT # Sample: Friday Sep 13, 2013 at 22:58 GMT


Okay fair enough, so yeh I agree with the naming stuff :D.

@BraedonWooding
Copy link
Member Author

Comment by bjubes
Sunday Feb 05, 2017 at 19:46 GMT # Sample: Friday Sep 13, 2013 at 22:58 GMT


maybe localizationKey is a better name? thats essentially what oxygen_generator is, a key that the localization system uses to find a value for based on the current language. It also makes it clear that localizaitonKey is not intented to be seen by the player and needs to be converted to the name.

perhaps adding in a functions documentation whether or not it takes the key/name as a perameter and whether it outputs the localization key or the translated name will also clarify things.

@BraedonWooding
Copy link
Member Author

Comment by koosemose
Monday Feb 06, 2017 at 01:46 GMT # Sample: Friday Sep 13, 2013 at 22:58 GMT


The problem is that they're all keys. What becomes the name is a Localization Key, and what becomes the description is a Localization Key. It's too generic, any one instance of an object may need to have Localization Keys to two (or maybe more eventually) different things. You could make it more specific with LocalizationKeyName and LocalizationKeyDescription (or would it read better as LocalizationNameKey and LocalizationDescriptionKey?), but in my opinion those are getting overly verbose and lengthy, and while clarity typically trumps brevity, I think those are length enough that in actual use it will hurt clarity as lines of code that have to use them will be very likely to span entirely too much horizontal space, and need to be spread over several lines, which, (again in my opinion) hurt clarity more.

To me the Localization in LocalizationName and LocalizationDescription signal clearly enough that they're meant to be used by the Localization system, and can be clarified more explicitly in the Property documentation. While it's only a 3 letter difference, they're already pushing towards what I consider to be too long, but can't think of any shorter way to refer to it without hurting clarity. And neither version that I can think of reads too well, feeling "clunky" and awkward which of course hurts recall of the proper Property/Field/Function to use in my opinion. The third that comes to mind and is still somewhat sensical would be NameLocalizationKey and DescriptionLocalizationKey, which may read better, but lose the recall benefits of both starting with "Localization" ( e.g. Need something for localization, but can't recall exactly what they are, so start typing Localization, and get the appropriate suggestions).

@kd7uiy
Copy link
Collaborator

kd7uiy commented Feb 18, 2019

This seems to be a standard, and I'm going to close this now.

@kd7uiy kd7uiy closed this as completed Feb 18, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants