Update doc for Translation

[timurt]

https://checkstyle.org/config_misc.html#Translation

Add example for each existing config to show what code is ok and what code cause violation.
Good example is https://checkstyle.org/config_naming.html#AbstractClassName

please play with module/Check by means of https://checkstyle.org/cmdline.html to understand how it works.

---

PLEASE READ https://github.com/checkstyle/checkstyle/wiki/Good-practice-on-how-to-update-examples

[timurt]

you have to update examples inside class file TranslationCheck and corresponding xdoc documentation config_misc.xml

you can find similar resolved issues here, you should do the same but for TranslationCheck

[timurt]

@harshitmalik03
OK, first of all can you please write here directly, instead of replying to emails. Replying to email puts whole conversation history in expandable box, which is redundant.

Let me explain issue more precisely. The main task of this issue is to provide good examples for configurations in example section. So that, every user could understand from site, where violation will occur. Please check similar issues with link I provided before

We can defined set of rules for commit messages and PR description, you can find them here

If you noticed, there are several continuous integration tools (TeamCity, Travis and etc) that checks code, please make sure they are all passed. You can find this automatic check section at the bottom of the your pull request page

[romani]

Please read https://github.com/checkstyle/checkstyle/wiki/Good-practice-on-how-to-update-examples

And it has example of how update should be done #7634 but you need to do this for Translation Check, similar update in xdoc file and javadoc of Check class.

[timurt]

How to run checkstyle

Lets start from the beginning, checkstyle can be assembled to jar file (as described here),

To be executed, jar requires configuration file (you can use as example this default one, but better to create simplified version by yourself) and input file (file, against which you want to perform check)

The following command will perform validation of your Test.java file based on rules from configuration file checks.xml:
$ java -jar checkstyle-8.xx-SNAPSHOT-all.jar -c checks.xml Test.java
If any violations occur during executing, they will be printed out to console

Scope of this issue

You can find different examples of TranslationCheck configurations inside config_misc.xml, for example

<module name="Translation">
  <property name="fileExtensions" value="properties, translations"/>
</module>

This configuration is not followed by example. As Checkstyle developer it is easy to understand what it does, but from ordinary user perspective, it is not so clear. We need to simplify users' lives by providing real example codes.

Almost every config section should be followed by corresponding example code, such approach can be observed from TodoComment documentation:

        <source>
&lt;module name=&quot;TodoComment&quot;&gt;
  &lt;property name=&quot;format&quot; value=&quot;(TODO)|(FIXME)&quot;/&gt;
&lt;/module&gt;
        </source>
        <p>
          Example:
        </p>
        <source>
i++;   // TODO: do differently in future   // violation
i++;   // todo: do differently in future   // OK
i=i/x; // FIXME: handle x = 0 case         // violation
i=i/x; // FIX :  handle x = 0 case         // OK
        </source>

What you need to do:

1. For every TranslationCheck config inside config_misc.xml add correct code sample and specify lines, where violation will occur
2. Make sure mvn clean verify command finishes successfully

I hoped my explanations were clear :)

[romani]

issue is not resolved.
Everyone in the world is welcome to send a fix.

[ShivamPandey00]

Is anyone still working on it ?
I would like to work on it.

[romani]

@coderdeadpool , we do not assign issues, just make comment "I am on it" and stat working on it

[Rishabh7798]

I want to work on this issue please assign me this task

[ShivamPandey00]

@romani Do we have to add seperate examples for each one of them,
like here, do we have to make seperate example of properties and translation ?

And same for es, fr and de here:

And should a violation be added like this ?

for example:
// violation 4 lines below on 'return' tag.
  /**
  * Some summary.
  *  @param a Some javadoc
  * @return

[romani]

This check requires at least two files as input.
requiredTranslations is only property that can be used to show how behavior becomes different on same input data but different config.

To show other properties in action we will need different input files. It is ok for this issue.

Comment in properties files should be # violation ..... and I think it is placed on whole file, line 1.

[romani]

fix is merged.
@coderdeadpool , did impressive work share clarity to the world.

[zww320]

Hello! I am aware that this issue is closed. I just have questions about the developing process.

After I modified xdoc, I tried mvn verify and I got XdocsJavaDocsTest.testAllCheckSectionJavaDocs. I tried to sync everything between xdoc and javadoc, but it still failed. I do not really under stand how to "sync documentation content between xml and java file" in a correct way. Could you please introduce the rules or refer to some docs?

Thanks in advance!

[ShivamPandey00]

@zwwang98 if your xdoc and javadoc do not sync properly, after doing mvn clean verify you will get the error message expected-code and actual- code, try to analyze it carefully. You will find the changes between xdoc and javadoc there.

[zww320]

@zwwang98 if your xdoc and javadoc do not sync properly, after doing mvn clean verify you will get the error message expected-code and actual- code, try to analyze it carefully. You will find the changes between xdoc and javadoc there.

Thank you @coderdeadpool , that is really helpful!