001/*
002 * SonarQube
003 * Copyright (C) 2009-2017 SonarSource SA
004 * mailto:info AT sonarsource DOT com
005 *
006 * This program is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 3 of the License, or (at your option) any later version.
010 *
011 * This program is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with this program; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019 */
020package org.sonar.api.i18n;
021
022import java.util.Locale;
023import javax.annotation.CheckForNull;
024import org.sonar.api.batch.ScannerSide;
025import org.sonar.api.rules.Rule;
026import org.sonar.api.ce.ComputeEngineSide;
027import org.sonar.api.server.ServerSide;
028
029/**
030 * {@link I18n}-companion component that provides translation facilities for rule names, descriptions and parameter names.
031 * 
032 * @since 3.2
033 * @deprecated in 4.1. Rules are not localized anymore. See http://jira.sonarsource.com/browse/SONAR-4885
034 */
035@Deprecated
036@ScannerSide
037@ServerSide
038@ComputeEngineSide
039public interface RuleI18n {
040
041  /**
042   * Returns the localized name of the rule identified by its repository key and rule key.
043   * <br>
044   * If the name is not found in the given locale, then the default name is returned (the English one).
045   * This method could return null if no default name found. This is the cause for instance the copies rules.
046   *
047   * @param repositoryKey the repository key
048   * @param ruleKey the rule key
049   * @param locale not used
050   * @return the translated name of the rule, or the default English one if the given locale is not supported, or null
051   * @deprecated since 4.1. Rules are not localized anymore. See http://jira.sonarsource.com/browse/SONAR-4885
052   */
053  @Deprecated
054  @CheckForNull
055  String getName(String repositoryKey, String ruleKey, Locale locale);
056
057  /**
058   * Returns the name of the rule identified by its repository key and rule key.
059   * <br>
060   * This method could return null if no default name found. This is the cause for instance the copies rules.
061   *
062   * @param repositoryKey the repository key
063   * @param ruleKey the rule key
064   * @return the nullable name of the rule
065   * @since 4.1
066   */
067  @CheckForNull
068  String getName(String repositoryKey, String ruleKey);
069
070  /**
071   * Returns the localized name or the name of the rule.
072   * <br>
073   * If the name is not found in the given locale, then the default name is returned (the English one).
074   * It the default name is not found, then the rule name is returned.
075   *
076   * @param rule the rule
077   * @param locale the locale to translate into
078   * @return the translated name of the rule, or the default English one if the given locale is not supported, or the rule name.
079   * @deprecated since 4.1. Rules are not localized anymore. See http://jira.sonarsource.com/browse/SONAR-4885
080   */
081  @Deprecated
082  @CheckForNull
083  String getName(Rule rule, Locale locale);
084
085  /**
086   * Returns the name of the rule.
087   * <br>
088   * It the default name is not found, then the rule name is returned.
089   *
090   * @param rule the rule
091   * @return the nullable name of the rule
092   * @since 4.1
093   */
094  @CheckForNull
095  String getName(Rule rule);
096
097  /**
098   * Returns the localized description of the rule identified by its repository key and rule key.
099   * <br>
100   * If the description is not found in the given locale, then the default description is returned (the English one).
101   * As a rule must have a description (this is a constraint in Sonar), this method never returns null.
102   *
103   * @param repositoryKey the repository key
104   * @param ruleKey the rule key
105   * @param locale  the locale to translate into
106   * @return the translated description of the rule, or the default English one if the given locale is not supported
107   * @deprecated since 4.1. Rules are not localized anymore. See http://jira.sonarsource.com/browse/SONAR-4885
108   */
109  @Deprecated
110  String getDescription(String repositoryKey, String ruleKey, Locale locale);
111
112  /**
113   * Returns the description of the rule identified by its repository key and rule key.
114   * <br>
115   * As a rule must have a description (this is a constraint in SonarQube), this method never returns null.
116   *
117   * @param repositoryKey the repository key
118   * @param ruleKey the rule key
119   * @return the description of the rule
120   * @since 4.1
121   */
122  String getDescription(String repositoryKey, String ruleKey);
123
124  /**
125   * Returns the localized name of the rule parameter identified by the rules's key and repository key, and by the parameter key.
126   * <br>
127   * If the name is not found in the given locale, then the English translation is searched and return if found. Otherwise,
128   * this method returns null (= if no translation can be found).
129   *
130   * @param repositoryKey the repository key
131   * @param ruleKey the rule key
132   * @param paramKey the parameter key
133   * @param locale the locale to translate into
134   * @return the translated name of the rule parameter, or the default English one if the given locale is not supported, or null if
135   *         no translation can be found.
136   * @deprecated since 4.1. Rules are not localized anymore. See http://jira.sonarsource.com/browse/SONAR-4885
137   */
138  @Deprecated
139  @CheckForNull
140  String getParamDescription(String repositoryKey, String ruleKey, String paramKey, Locale locale);
141
142  /**
143   * Returns the name of the rule parameter identified by the rules's key and repository key, and by the parameter key.
144   *
145   * @param repositoryKey the repository key
146   * @param ruleKey the rule key
147   * @param paramKey the parameter key
148   * @return the nullable name of the rule parameter
149   * @since 4.1
150   */
151  @CheckForNull
152  String getParamDescription(String repositoryKey, String ruleKey, String paramKey);
153
154}