Gitea: English translation grammar and consistency

[bugreport0]

Description

A product like Gitea needs an impeccable and consistent voice to deliver a smooth user experience, but the current English (source) translation is sub-optimal. An initial broad scan brought up some grammatical and stylistic problems. I don't want to trample all over locale_en-US.ini with a mammoth PR—consider this issue a place for discussion.

Not exactly sure how to suggest improvements, so listing them in this issue with relevant line numbers and identifiers. This first list is far from exhaustive. If you welcome more effort in this department, let me know.

Grammar

• 252 : git_ref_name_error —> 'must be [a] well formed git reference name.'
• 338 : [uploaded_avatar_not_an_image] —> 'Uploaded file is not [an] image.'
• 917: settings.transfer_notices_1 —> '- You will lose access if the new owner is [an] individual user.'

User Interface

The dedicated ellipsis character … should be used instead of repeating three period characters ... to improve text layout. Compare the rendering of 'New…' (ellipsis) with 'New...' (periods).

A unit test can make sure that ... is never allowed in future strings and translations. Currently 12 English strings are in violation.

Consistency and Style

This list is more subjective, but I think consistent choices must be made to make sure a user isn't presented with conflicting information and presentation. Some items list the amount of times each alternative is currently present in (italic numbers).

• do we want to use username (25 times) or user name (2 times)?
• do we want to use admin (16 times) or administrator (6 times)?
• do we want to use cannot (29 times), can not (5 times) or can't (1 time)?
• do we want no space before each ellipsis (…) (10 times) or a space (2 times)?
• 264 : repo_name_been_taken —> 'Repository name already used.' — do we want to rename this identifier to use 'used' or use 'taken' in the string?
• 714 : issues.attachment.open_tab and 715 : issues.attachment.download —> I think we should use '%s' (single quotes) for consistency instead of "%s" (double quotes)

[lafriks]

I fully agree with you but currently I think majority of gitea developers are non-native English speakers :) So if anyone would volunteer to fix en_US.ini file and/or help also in future than that would be just great :)

[geop929]

A lot of junk files

[bugreport0]

I've just created a first PR #3518 to fix some low-hanging fruit that should be an objective improvement. Leaving more subjective choices for discussion.

[bugreport0]

@lafriks : Should I try and go through the entire English translation to submit more PRs like #3518 ? Also, see my comment about unit tests there. I think we'd definitely want to document and automate basic style checking for all translations.

[lafriks]

@bugreport0 yes please do so, that would be great :)

As for rules most probably we would need tool that would check them on PRs. We already have one but it checks only basic spelling issues

[kolaente]

On the same note, is there a reason why there are multiple strings which mean exactly the same?
For example we have repo:editor.new_branch_name_desc and form:NewBranchName which both translates to "New branch name". IMHO only one should be used.

[lafriks]

It just in case if in other languages it could be that translation for them is not in the same form

[bugreport0]

@lafriks can you, or any of the other project members, (help) describe the tone of voice you (want to) use for Gitea? This is independent of the actual language and there's no 'best' choice here, but we should stick to one style.

I'm looking for choices like (this list is not exhaustive):

• formal versus informal
• restrained versus high-energy
• consistent versus random

Each option affects the actual wording. For instance, right now we (informally) use the noun 'email' to refer to an 'email address'. A formal translation would actually use 'email address'.

I've been eyeing the translation for days now and found many opportunities for improvement, but I need to know the tone of voice. This is pretty much akin to setting out coding guidelines, except for natural languages. Other translations will benefit from documenting this as well.

Minor edit (addition): a products voice and phrasing is the first and most visible thing that users see. It's important to document our guidelines and polish this.

[lafriks]

I personally prefer formal, restrained and consistent but in every place it need to be verified with layout not to have too long words for labels etc otherwise it can break layout

[bugreport0]

Working on the translation. It's hard work and takes a lot of time to get consistent. I'm also finding UI problems left and right. Here's a first PR #3564 .

[thehowl]

To be honest, though, I disagree with @lafriks' comment, I'd rather not have it _too_ formal. This is especially important for other languages: German has the "Sie" form, in italian we use "lei". If we wanted to be formal, these structures would have to be used in the languages which support it. And as a native Italian speaker, I can say that I often hate services which refer to me using "lei", mostly because it seems waaaay too over the top.

Instead, I'd argue to use the kind of tone that other code hosting services use, like GitHub and GitLab, because that's what most users will be used to. Although I wouldn't be able to tell specifically how it should be. Generally, though, I can say I like correct grammar and simple sentences; a language easily readable by non-native speakers, and that has as the main priority getting the point across.

I'd say that this writing style guide can, for the most part, apply to gitea: https://material.io/guidelines/style/writing.html#writing-language

[bugreport0]

@thehowl Thanks, that writing guide meshes very well with the style I'm using. You're entirely right about not being too polite; we just need to be practical, consistent and 'easy to use' (whatever we make of that).

One thing I'm wondering though: Gitea is positioned as a self-hosted solution, right? Wouldn't this limit us to (at most) small to medium size companies? I'm thinking of replacing the concept of 'organizations' with 'teams'. We're not a service like Github, so I think it'd make a lot of sense to scale down our user interface terminology accordingly.

I'll try to create a PR this week with my preliminary work on locale_en-US.ini so we can discuss a bit. I've already put in dozens of hours hammering away at inconsistencies.

[kolaente]

I'm thinking of replacing the concept of 'organizations' with 'teams'.

I like the idea, but I think this has already been discussed somewhere. As organisations can have teams, this would probably be confusing.
Maybe "Projects" would be a better fit?

[thehowl]

Projects doesn't cut it either, because then someone could mix it up with repository and not get the difference. I'd propose what GitLab uses, which is "Group", which I think works quite well in this context (GitLab also uses the term "Subgroup" instead of "Team").

[bugreport0]

@thehowl Group is a solid term. Sounds both informal and formal simultaneously. Subgroup is a logical step beyond it. Anyone else want to chime in?

[bugreport0]

Still slogging through the interface (#3589 #3590 #3605 and more) and fixing strings left and right. Will try to post a WIP PR tomorrow. I think I've touched about 40% of the UI now, but it's getting harder and harder to keep the translation consistent due to UI quirks.

[bugreport0]

Promise is promise: #3614

[bugreport0]

Quick tally: @thehowl and @lafriks tend to agree that 'Group' and 'Subgroup' might be better terms for the current 'Organization' and 'Team' split. @techknowlogick and @lunny think that keeping the existing terms might be better.

I've updated #3614 to temporarily exclude any changes in terminology for now. Please keep this issue open until we've drafted a definite plan forward.

[lafriks]

I like Group and Team combination ;)

[kolaente]

I dont think we should rename it. There's at least one issue which asks for global user groups, so I'm thinking we're gonna implement this at some point. And then it will be really confusing to seperate goups (former orgs) and global groups.

[lafriks]

Closing this issue as already fixed