diff --git a/src/v2/style-guide/index.md b/src/v2/style-guide/index.md index c007725b84..bd36e3720a 100644 --- a/src/v2/style-guide/index.md +++ b/src/v2/style-guide/index.md @@ -2,54 +2,54 @@ type: style-guide --- -# Style Guide beta +# Guía de Estilo beta -This is the official style guide for Vue-specific code. If you use Vue in a project, it's a great reference to avoid errors, bikeshedding, and anti-patterns. However, we don't believe that any style guide is ideal for all teams or projects, so mindful deviations are encouraged based on past experience, the surrounding tech stack, and personal values. +Esta es la guía de estilo oficial para el código específico de Vue. Si usa Vue en un proyecto, es una gran referencia para evitar errores, código innecesario y anti-patrones. Sin embargo, no creemos que ninguna guía de estilo sea ideal para todos los equipos o proyectos, por lo que se recomienda tener en cuenta las desviaciones basadas en experiencias pasadas, la tecnología del entorno y los valores personales. -For the most part, we also avoid suggestions about JavaScript or HTML in general. We don't mind whether you use semicolons or trailing commas. We don't mind whether your HTML uses single-quotes or double-quotes for attribute values. Some exceptions will exist however, where we've found that a particular pattern is helpful in the context of Vue. +En su mayor parte, también evitamos sugerencias sobre JavaScript o HTML en general. No nos importa si usa punto y coma al final de sus líneas. No nos importa si su HTML utiliza comillas simples o dobles para los valores de los atributos. Sin embargo, existirán algunas excepciones, donde hemos encontrado que un patrón particular es útil en el contexto de Vue. -> **Soon, we'll also provide tips for enforcement.** Sometimes you'll simply have to be disciplined, but wherever possible, we'll try to show you how to use ESLint and other automated processes to make enforcement simpler. +> **Pronto, también le daremos consejos para la aplicación de formato.** A veces simplemente tendrá que ser disciplinado, pero siempre que sea posible, trataremos de mostrarte cómo usar ESLint y otros procesos automatizados para hacer más simple la aplicación de formato. -Finally, we've split rules into four categories: +Finalmente, hemos dividido las reglas en cuatro categorías: -## Rule Categories +## Categorías de reglas -### Priority A: Essential +### Prioridad A: Esencial -These rules help prevent errors, so learn and abide by them at all costs. Exceptions may exist, but should be very rare and only be made by those with expert knowledge of both JavaScript and Vue. +Estas reglas ayudan a prevenir errores, así que aprenda y adóptelas a toda costa. Las excepciones pueden existir, pero deben ser muy raras y sólo deben ser realizadas por aquellos con conocimiento experto tanto de JavaScript como de Vue. -### Priority B: Strongly Recommended +### Prioridad B: Altamente recomendado -These rules have been found to improve readability and/or developer experience in most projects. Your code will still run if you violate them, but violations should be rare and well-justified. +Se ha comprobado que estas reglas mejoran la legibilidad y/o la experiencia del desarrollador en la mayoría de los proyectos. El código seguirá funcionando si no se aplican, pero las infracciones deben ser raras y bien justificadas. -### Priority C: Recommended +### Prioridad C: Recomendado -Where multiple, equally good options exist, an arbitrary choice can be made to ensure consistency. In these rules, we describe each acceptable option and suggest a default choice. That means you can feel free to make a different choice in your own codebase, as long as you're consistent and have a good reason. Please do have a good reason though! By adapting to the community standard, you will: +Cuando existen varias opciones igualmente buenas, se puede hacer una elección arbitraria para garantizar la consistencia. En estas reglas, describimos cada opción aceptable y sugerimos una opción por defecto. Esto significa que puede sentirse libre de tomar una decisión diferente en su propia base de código, siempre y cuando sea consistente y tenga una buena razón. Pero por favor, ¡Que tenga una buena razón! Al adaptarse al estándar de la comunidad, podrá: -1. train your brain to more easily parse most of the community code you encounter -2. be able to copy and paste most community code examples without modification -3. often find new hires are already accustomed to your preferred coding style, at least in regards to Vue +1. entrenar su cerebro para analizar más fácilmente la mayor parte del código de la comunidad que encuentre +2. poder copiar y pegar la mayoría de los ejemplos de código comunitarios sin necesidad de modificarlos +3. encontrar a menudo que los nuevos empleados ya estén acostumbrados a su estilo de codificación preferido, al menos en lo que respecta a Vue -### Priority D: Use with Caution +### Prioridad D: Uso con Precaución -Some features of Vue exist to accommodate rare edge cases or smoother migrations from a legacy code base. When overused however, they can make your code more difficult to maintain or even become a source of bugs. These rules shine a light on potentially risky features, describing when and why they should be avoided. +Algunas características de Vue existen para acomodar casos extremos o migraciones más fluidas desde una base de código heredada. Sin embargo, cuando se usan en exceso, pueden hacer que su código sea más difícil de mantener o incluso convertirse en una fuente de errores. Estas reglas arrojan luz sobre las características potencialmente riesgosas, describiendo cuándo y por qué deben evitarse. -## Priority A Rules: Essential (Error Prevention) +## Reglas de prioridad A: Esencial (Prevención de errores) -### Multi-word component names essential +### Nombres multi-palabra para componentes esencial -**Component names should always be multi-word, except for root `App` components.** +**Los nombres de los componentes deben ser siempre de varias palabras, excepto para los componentes de la raíz `App`.** -This [prevents conflicts](http://w3c.github.io/webcomponents/spec/custom/#valid-custom-element-name) with existing and future HTML elements, since all HTML elements are a single word. +Esto [evita conflictos](http://w3c.github.io/webcomponents/spec/custom/#valid-custom-element-name) con elementos HTML existentes y futuros, ya que todos los elementos HTML están compuestos por una sola palabra. {% raw %}
{% endraw %} -#### Bad +#### Mal ``` js Vue.component('todo', { @@ -66,7 +66,7 @@ export default { {% raw %}
{% endraw %} {% raw %}
{% endraw %} -#### Good +#### Bien ``` js Vue.component('todo-item', { @@ -84,20 +84,20 @@ export default { -### Component data essential +### Datos de los componentes esencial -**Component `data` must be a function.** +**En un componente, `data` tiene que ser una función.** -When using the `data` property on a component (i.e. anywhere except on `new Vue`), the value must be a function that returns an object. +Cuando se usa la propiedad `data` en un componente (es decir, en cualquier lugar excepto en `new Vue`), el valor debe ser una función que devuelva un objeto. {% raw %}
-

Detailed Explanation

+

Explicación Detallada

 {% endraw %} -When the value of `data` is an object, it's shared across all instances of a component. Imagine, for example, a `TodoList` component with this data: +Cuando el valor de `data` es un objeto, se comparte entre todas las instancias de un componente. Imagina, por ejemplo, un componente `TodoList` con estos datos: ``` js data: { @@ -106,9 +106,9 @@ data: { } ``` -We might want to reuse this component, allowing users to maintain multiple lists (e.g. for shopping, wishlists, daily chores, etc). There's a problem though. Since every instance of the component references the same data object, changing the title of one list will also change the title of every other list. The same is true for adding/editing/deleting a todo. +Es posible que queramos reutilizar este componente, permitiendo a los usuarios mantener múltiples listas (por ejemplo, para hacer compras, listas de deseos, tareas diarias, etc.). Pero hay un problema, dado que cada instancia del componente hace referencia al mismo objeto de datos, el cambio del título de una lista también cambiará el título de todas las demás listas. Lo mismo se aplica para añadir/editar/eliminar una lista. -Instead, we want each component instance to only manage its own data. For that to happen, each instance must generate a unique data object. In JavaScript, this can be accomplished by returning the object in a function: +En su lugar, queremos que cada instancia de un componente sólo gestione sus propios datos. Para que esto suceda, cada instancia debe generar un objeto de datos único. En JavaScript, esto se puede lograr devolviendo el objeto en una función: ``` js data: function () { @@ -121,7 +121,7 @@ data: function () { {% raw %}
{% endraw %} {% raw %}
{% endraw %} -#### Bad +#### Mal ``` js Vue.component('some-comp', { @@ -141,7 +141,7 @@ export default { {% raw %}
{% endraw %} {% raw %}
{% endraw %} -#### Good +#### Bien ``` js Vue.component('some-comp', { data: function () { @@ -153,7 +153,7 @@ Vue.component('some-comp', { ``` ``` js -// In a .vue file +// En un archivo .vue export default { data () { return { @@ -164,9 +164,8 @@ export default { ``` ``` js -// It's OK to use an object directly in a root -// Vue instance, since only a single instance -// will ever exist. +// Está bien usar un objeto directamente en una instancia +// raíz de Vue, ya que sólo existirá una única instancia. new Vue({ data: { foo: 'bar' @@ -177,37 +176,37 @@ new Vue({ -### Prop definitions essential +### Definiciones de prop esencial -**Prop definitions should be as detailed as possible.** +**Las definiciones de prop deben ser lo más detalladas posible** -In committed code, prop definitions should always be as detailed as possible, specifying at least type(s). +En el código enviado a un repositorio, las definiciones de los props deben ser siempre tan detalladas como sea posible, especificando al menos el tipo o tipos. {% raw %}
-

Detailed Explanation

+

Explicación Detallada

 {% endraw %} -Detailed [prop definitions](https://vuejs.org/v2/guide/components.html#Prop-Validation) have two advantages: +Las [definiciones detalladas de los props](https://vuejs.org/v2/guide/components.html#Prop-Validation) tienen dos ventajas: -- They document the API of the component, so that it's easy to see how the component is meant to be used. -- In development, Vue will warn you if a component is ever provided incorrectly formatted props, helping you catch potential sources of error. +- Documentan la API del componente, de modo que es fácil ver cómo debe ser utilizado. +- Durante el desarrollo, Vue le advertirá si un componente se proporciona con un formato incorrecto, lo que le ayudará a detectar posibles fuentes de error. {% raw %}
{% endraw %} {% raw %}
{% endraw %} -#### Bad +#### Mal ``` js -// This is only OK when prototyping +// Esto esta bien únicamete durante el prototipado props: ['status'] ``` {% raw %}
{% endraw %} {% raw %}
{% endraw %} -#### Good +#### Bien ``` js props: { @@ -216,7 +215,7 @@ props: { ``` ``` js -// Even better! +// ¡Aún mejor! props: { status: { type: String, @@ -236,20 +235,20 @@ props: { -### Keyed `v-for` essential +### Keys (claves) en un `v-for` esencial -**Always use `key` with `v-for`.** +**Usa siempre `key` con `v-for`.** -`key` with `v-for` is _always_ required on components, in order to maintain internal component state down the subtree. Even for elements though, it's a good practice to maintain predictable behavior, such as [object constancy](https://bost.ocks.org/mike/constancy/) in animations. +El `key` en un `v-for` es _siempre_ necesario en los componentes, para mantener el estado interno de los componentes en el subárbol. Incluso para los elementos, sin embargo, es una buena práctica mantener un comportamiento predecible, como la [constancia de objetos](https://bost.ocks.org/mike/constancy/) en las animaciones. {% raw %}
-

Detailed Explanation

+

Explicación Detallada

 {% endraw %} -Let's say you have a list of todos: +Digamos que tienes una lista de pendientes: ``` js data: function () { @@ -268,16 +267,16 @@ data: function () { } ``` -Then you sort them alphabetically. When updating the DOM, Vue will optimize rendering to perform the cheapest DOM mutations possible. That might mean deleting the first todo element, then adding it again at the end of the list. +Luego los ordenas alfabéticamente. Al actualizar el DOM, Vue optimizará el renderizado para realizar las mutaciones DOM más eficientes posibles. Esto podría significar borrar el primer elemento de la lista, y luego agregarlo de nuevo al final de la lista. -The problem is, there are cases where it's important not to delete elements that will remain in the DOM. For example, you may want to use `` to animate list sorting, or maintain focus if the rendered element is an ``. In these cases, adding a unique key for each item (e.g. `:key="todo.id"`) will tell Vue how to behave more predictably. +El problema es que hay casos en los que es importante no borrar los elementos que permanecerán en el DOM. Por ejemplo, puede usar `` para animar la ordenación de la lista o mantener el foco si el elemento renderizado es un ``. En estos casos, añadir una clave única para cada elemento (por ejemplo, ``:key="todo.id"`) le dirá a Vue cómo comportarse de forma más predecible. -In our experience, it's better to _always_ add a unique key, so that you and your team simply never have to worry about these edge cases. Then in the rare, performance-critical scenarios where object constancy isn't necessary, you can make a conscious exception. +En nuestra experiencia, es mejor _siempre_ agregar una clave única, para que usted y su equipo simplemente nunca tengan que preocuparse por estos casos extremos. Entonces, en los raros y críticos escenarios donde la constancia de los objetos no es necesaria, puedes hacer una excepción consciente. {% raw %}
{% endraw %} {% raw %}
{% endraw %} -#### Bad +#### Mal ``` html
    @@ -289,7 +288,7 @@ In our experience, it's better to _always_ add a unique key, so that you and you {% raw %}
{% endraw %} {% raw %}
{% endraw %} -#### Good +#### Bien ``` html
    @@ -305,31 +304,31 @@ In our experience, it's better to _always_ add a unique key, so that you and you -### Component style scoping essential +### Alcance del estilo de componentes esencial -**For applications, styles in a top-level `App` component and in layout components may be global, but all other components should always be scoped.** +**Para las aplicaciones, los estilos en un componente de `App` del nivel superior y en los componentes de diseño pueden ser globales, pero todos los demás componentes deben tener siempre un alcance.** -This is only relevant for [single-file components](../guide/single-file-components.html). It does _not_ require that the [`scoped` attribute](https://vue-loader.vuejs.org/en/features/scoped-css.html) be used. Scoping could be through [CSS modules](https://vue-loader.vuejs.org/en/features/css-modules.html), a class-based strategy such as [BEM](http://getbem.com/), or another library/convention. +Esto sólo es relevante para [componentes de un sólo archivo](../guide/single-file-components.html). Que _No requiere_ que se utilice el atributo[`scoped`](https://vue-loader.vuejs.org/en/features/scoped-css.html). El alcance podría ser a través de [módulos CSS](https://vue-loader.vuejs.org/en/features/css-modules.html), una estrategia basada en clases como [BEM](http://getbem.com/), u otra librería/convención. -**Component libraries, however, should prefer a class-based strategy instead of using the `scoped` attribute.** +**Las librerías de componentes, sin embargo, deberían preferir una estrategia basada en clases en lugar de usar el atributo `scoped` **. -This makes overriding internal styles easier, with human-readable class names that don't have too high specificity, but are still very unlikely to result in a conflict. +Esto facilita el override de los estilos internos, con nombres de clase legibles por el ser humano que no tienen una especificidad demasiado alta, pero que aún así es muy poco probable que provoquen un conflicto. {% raw %}
    -

    Detailed Explanation

    +

    Explicación Detallada

     {% endraw %} -If you are developing a large project, working with other developers, or sometimes include 3rd-party HTML/CSS (e.g. from Auth0), consistent scoping will ensure that your styles only apply to the components they are meant for. +Si está desarrollando un proyecto grande, trabajando con otros desarrolladores, o a veces incluye HTML/CSS de terceros (p.ej. de Auth0), un alcance consistente asegurará que sus estilos sólo se apliquen a los componentes para los que están diseñados. -Beyond the `scoped` attribute, using unique class names can help ensure that 3rd-party CSS does not apply to your own HTML. For example, many projects use the `button`, `btn`, or `icon` class names, so even if not using a strategy such as BEM, adding an app-specific and/or component-specific prefix (e.g. `ButtonClose-icon`) can provide some protection. +Más allá del atributo `scoped`, el uso de nombres de clase únicos puede ayudar a asegurar que el CSS de terceros no se aplique a su propio HTML. Por ejemplo, muchos proyectos utilizan los nombres de clase `button`, `btn`, o `icon`, de modo que incluso si no se utiliza una estrategia como BEM, añadir un prefijo específico de la aplicación y/o un prefijo específico del componente (por ejemplo, `ButtonClose-icon') puede proporcionar cierta protección. {% raw %}
    {% endraw %} {% raw %}
    {% endraw %} -#### Bad +#### Mal ``` html